mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
Two Windows agent-loop friction fixes: 1. tools/mcp_tool.py (#56536): shutil.which(cmd, path=env_path) reads executable extensions from the PARENT process PATHEXT, not the MCP subprocess env — a stdio MCP config supplying both PATH and PATHEXT could fail to resolve a command its own env can locate, and startup then got a bare command name. On Windows, when the first which() call misses and the config env carries PATHEXT (any key casing), retry the resolution with the config's PATHEXT temporarily applied. 2. skills/ + optional-skills/ (#50606): 42 SKILL.md files that declare platforms: [.., windows] used python3 in their command examples. python3 does not exist on native Windows (the toolchain probe in the system prompt reports python3=missing), so every copy-pasted example burned a failed agent turn before self-correction. Replaced the command word python3 -> python (python3-config / python3.x version strings untouched). python is the spelling that exists in every Hermes-managed environment (Windows native, uv-managed venvs on all three OSes); agents on POSIX hosts additionally see the probed toolchain line and adapt either way.
300 lines
8 KiB
Markdown
300 lines
8 KiB
Markdown
---
|
|
name: fastmcp
|
|
description: Build, test, and deploy Python MCP servers.
|
|
version: 1.0.0
|
|
author: Hermes Agent
|
|
license: MIT
|
|
platforms: [linux, macos, windows]
|
|
metadata:
|
|
hermes:
|
|
tags: [MCP, FastMCP, Python, Tools, Resources, Prompts, Deployment]
|
|
homepage: https://gofastmcp.com
|
|
related_skills: [hermes-agent, mcporter]
|
|
prerequisites:
|
|
commands: [python]
|
|
---
|
|
|
|
# FastMCP
|
|
|
|
Build MCP servers in Python with FastMCP, validate them locally, install them into MCP clients, and deploy them as HTTP endpoints.
|
|
|
|
## When to Use
|
|
|
|
Use this skill when the task is to:
|
|
|
|
- create a new MCP server in Python
|
|
- wrap an API, database, CLI, or file-processing workflow as MCP tools
|
|
- expose resources or prompts in addition to tools
|
|
- smoke-test a server with the FastMCP CLI before wiring it into Hermes or another client
|
|
- install a server into Claude Code, Claude Desktop, Cursor, or a similar MCP client
|
|
- prepare a FastMCP server repo for HTTP deployment
|
|
|
|
Use `native-mcp` when the server already exists and only needs to be connected to Hermes. Use `mcporter` when the goal is ad-hoc CLI access to an existing MCP server instead of building one.
|
|
|
|
## Prerequisites
|
|
|
|
Install FastMCP in the working environment first:
|
|
|
|
```bash
|
|
pip install fastmcp
|
|
fastmcp version
|
|
```
|
|
|
|
For the API template, install `httpx` if it is not already present:
|
|
|
|
```bash
|
|
pip install httpx
|
|
```
|
|
|
|
## Included Files
|
|
|
|
### Templates
|
|
|
|
- `templates/api_wrapper.py` - REST API wrapper with auth header support
|
|
- `templates/database_server.py` - read-only SQLite query server
|
|
- `templates/file_processor.py` - text-file inspection and search server
|
|
|
|
### Scripts
|
|
|
|
- `scripts/scaffold_fastmcp.py` - copy a starter template and replace the server name placeholder
|
|
|
|
### References
|
|
|
|
- `references/fastmcp-cli.md` - FastMCP CLI workflow, installation targets, and deployment checks
|
|
|
|
## Workflow
|
|
|
|
### 1. Pick the Smallest Viable Server Shape
|
|
|
|
Choose the narrowest useful surface area first:
|
|
|
|
- API wrapper: start with 1-3 high-value endpoints, not the whole API
|
|
- database server: expose read-only introspection and a constrained query path
|
|
- file processor: expose deterministic operations with explicit path arguments
|
|
- prompts/resources: add only when the client needs reusable prompt templates or discoverable documents
|
|
|
|
Prefer a thin server with good names, docstrings, and schemas over a large server with vague tools.
|
|
|
|
### 2. Scaffold from a Template
|
|
|
|
Copy a template directly or use the scaffold helper:
|
|
|
|
```bash
|
|
python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \
|
|
--template api_wrapper \
|
|
--name "Acme API" \
|
|
--output ./acme_server.py
|
|
```
|
|
|
|
Available templates:
|
|
|
|
```bash
|
|
python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list
|
|
```
|
|
|
|
If copying manually, replace `__SERVER_NAME__` with a real server name.
|
|
|
|
### 3. Implement Tools First
|
|
|
|
Start with `@mcp.tool` functions before adding resources or prompts.
|
|
|
|
Rules for tool design:
|
|
|
|
- Give every tool a concrete verb-based name
|
|
- Write docstrings as user-facing tool descriptions
|
|
- Keep parameters explicit and typed
|
|
- Return structured JSON-safe data where possible
|
|
- Validate unsafe inputs early
|
|
- Prefer read-only behavior by default for first versions
|
|
|
|
Good tool examples:
|
|
|
|
- `get_customer`
|
|
- `search_tickets`
|
|
- `describe_table`
|
|
- `summarize_text_file`
|
|
|
|
Weak tool examples:
|
|
|
|
- `run`
|
|
- `process`
|
|
- `do_thing`
|
|
|
|
### 4. Add Resources and Prompts Only When They Help
|
|
|
|
Add `@mcp.resource` when the client benefits from fetching stable read-only content such as schemas, policy docs, or generated reports.
|
|
|
|
Add `@mcp.prompt` when the server should provide a reusable prompt template for a known workflow.
|
|
|
|
Do not turn every document into a prompt. Prefer:
|
|
|
|
- tools for actions
|
|
- resources for data/document retrieval
|
|
- prompts for reusable LLM instructions
|
|
|
|
### 5. Test the Server Before Integrating It Anywhere
|
|
|
|
Use the FastMCP CLI for local validation:
|
|
|
|
```bash
|
|
fastmcp inspect acme_server.py:mcp
|
|
fastmcp list acme_server.py --json
|
|
fastmcp call acme_server.py search_resources query=router limit=5 --json
|
|
```
|
|
|
|
For fast iterative debugging, run the server locally:
|
|
|
|
```bash
|
|
fastmcp run acme_server.py:mcp
|
|
```
|
|
|
|
To test HTTP transport locally:
|
|
|
|
```bash
|
|
fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000
|
|
fastmcp list http://127.0.0.1:8000/mcp --json
|
|
fastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json
|
|
```
|
|
|
|
Always run at least one real `fastmcp call` against each new tool before claiming the server works.
|
|
|
|
### 6. Install into a Client When Local Validation Passes
|
|
|
|
FastMCP can register the server with supported MCP clients:
|
|
|
|
```bash
|
|
fastmcp install claude-code acme_server.py
|
|
fastmcp install claude-desktop acme_server.py
|
|
fastmcp install cursor acme_server.py -e .
|
|
```
|
|
|
|
Use `fastmcp discover` to inspect named MCP servers already configured on the machine.
|
|
|
|
When the goal is Hermes integration, either:
|
|
|
|
- configure the server in `~/.hermes/config.yaml` using the `native-mcp` skill, or
|
|
- keep using FastMCP CLI commands during development until the interface stabilizes
|
|
|
|
### 7. Deploy After the Local Contract Is Stable
|
|
|
|
For managed hosting, Prefect Horizon is the path FastMCP documents most directly. Before deployment:
|
|
|
|
```bash
|
|
fastmcp inspect acme_server.py:mcp
|
|
```
|
|
|
|
Make sure the repo contains:
|
|
|
|
- a Python file with the FastMCP server object
|
|
- `requirements.txt` or `pyproject.toml`
|
|
- any environment-variable documentation needed for deployment
|
|
|
|
For generic HTTP hosting, validate the HTTP transport locally first, then deploy on any Python-compatible platform that can expose the server port.
|
|
|
|
## Common Patterns
|
|
|
|
### API Wrapper Pattern
|
|
|
|
Use when exposing a REST or HTTP API as MCP tools.
|
|
|
|
Recommended first slice:
|
|
|
|
- one read path
|
|
- one list/search path
|
|
- optional health check
|
|
|
|
Implementation notes:
|
|
|
|
- keep auth in environment variables, not hardcoded
|
|
- centralize request logic in one helper
|
|
- surface API errors with concise context
|
|
- normalize inconsistent upstream payloads before returning them
|
|
|
|
Start from `templates/api_wrapper.py`.
|
|
|
|
### Database Pattern
|
|
|
|
Use when exposing safe query and inspection capabilities.
|
|
|
|
Recommended first slice:
|
|
|
|
- `list_tables`
|
|
- `describe_table`
|
|
- one constrained read query tool
|
|
|
|
Implementation notes:
|
|
|
|
- default to read-only DB access
|
|
- reject non-`SELECT` SQL in early versions
|
|
- limit row counts
|
|
- return rows plus column names
|
|
|
|
Start from `templates/database_server.py`.
|
|
|
|
### File Processor Pattern
|
|
|
|
Use when the server needs to inspect or transform files on demand.
|
|
|
|
Recommended first slice:
|
|
|
|
- summarize file contents
|
|
- search within files
|
|
- extract deterministic metadata
|
|
|
|
Implementation notes:
|
|
|
|
- accept explicit file paths
|
|
- check for missing files and encoding failures
|
|
- cap previews and result counts
|
|
- avoid shelling out unless a specific external tool is required
|
|
|
|
Start from `templates/file_processor.py`.
|
|
|
|
## Quality Bar
|
|
|
|
Before handing off a FastMCP server, verify all of the following:
|
|
|
|
- server imports cleanly
|
|
- `fastmcp inspect <file.py:mcp>` succeeds
|
|
- `fastmcp list <server spec> --json` succeeds
|
|
- every new tool has at least one real `fastmcp call`
|
|
- environment variables are documented
|
|
- the tool surface is small enough to understand without guesswork
|
|
|
|
## Troubleshooting
|
|
|
|
### FastMCP command missing
|
|
|
|
Install the package in the active environment:
|
|
|
|
```bash
|
|
pip install fastmcp
|
|
fastmcp version
|
|
```
|
|
|
|
### `fastmcp inspect` fails
|
|
|
|
Check that:
|
|
|
|
- the file imports without side effects that crash
|
|
- the FastMCP instance is named correctly in `<file.py:object>`
|
|
- optional dependencies from the template are installed
|
|
|
|
### Tool works in Python but not through CLI
|
|
|
|
Run:
|
|
|
|
```bash
|
|
fastmcp list server.py --json
|
|
fastmcp call server.py your_tool_name --json
|
|
```
|
|
|
|
This usually exposes naming mismatches, missing required arguments, or non-serializable return values.
|
|
|
|
### Hermes cannot see the deployed server
|
|
|
|
The server-building part may be correct while the Hermes config is not. Load the `native-mcp` skill and configure the server in `~/.hermes/config.yaml`, then restart Hermes.
|
|
|
|
## References
|
|
|
|
For CLI details, install targets, and deployment checks, read `references/fastmcp-cli.md`.
|