{
  "markdown": "# FastMCP Engineering\n\nEngineering methodology, research artifacts, skills, prompts, contracts, and quality gates for building production-grade MCP servers with FastMCP.\n\n## Core principles\n\n- Research official documentation and official examples before making framework decisions.\n- Separate domain, application, infrastructure, and MCP delivery responsibilities.\n- Prefer the simplest architecture that satisfies real requirements.\n- Use SOLID, KISS, DRY, and YAGNI as decision criteria, not as reasons to add abstractions.\n- Prefer native FastMCP capabilities before custom infrastructure.\n- Keep Pydantic, SQLAlchemy, PydanticAI, Supabase, and other technologies behind appropriate boundaries.\n- Verify behavior with tests, protocol checks, security review, and architecture review.\n- Treat documentation and repository hygiene as part of correctness.\n\n## Engineering workflow\n\nPreflight → Requirement → Discovery → Documentation Research → Example Research → Architecture → Design Gate → Contracts → TDD → Implementation → Documentation Sync → Static Analysis → Tests → Security Review → Architecture Review → PR Review → Merge → Delete Source Branch → Verify `main` → Branch Audit.\n\n## GitHub workflow\n\n`main` is the only persistent branch. Work is performed on one short-lived intent-named branch with exactly one PR:\n\n```text\nmain → feat/fix/refactor/docs/chore branch → PR → review → merge → delete branch → verify main\n```\n\nA branch without a PR is orphan work. A merged PR whose source branch survives is incomplete work. If branch deletion is unavailable through the current tooling, completion must be reported as blocked.\n\n## Verification without CI\n\nGitHub Actions are optional and are not a prerequisite for development or merge. When CI is unavailable, run the strongest applicable local checks: tests, lint, type checks, builds, static analysis, protocol/conformance checks, and security checks. Never invent CI results and never lower the verification standard because CI is unavailable.\n\n## Documentation synchronization\n\nChanges to externally relevant behavior, architecture, API, configuration, operations, testing procedures, or agent workflow must update the relevant documentation in the same PR. Intentional documentation non-changes must be explained in the review evidence.\n\n## Version policy\n\nFastMCP version-specific claims must identify their version and stability level. Stable and prerelease APIs must never be silently mixed.\n\n## Status\n\nConsolidated engineering foundation. The repository contains canonical skills, prompts, contracts, architecture guidance, research artifacts, and verification rules. New implementation work follows the branch/PR lifecycle above.\n\n## Installation (all agents)\n\nFastMCP Engineering auto-triggers its skills in every major coding agent. Install\nthrough each harness's own mechanism (never by hand-copying files):\n\n| Harness | Install | Details |\n|---|---|---|\n| Claude Code | `/plugin install ...` | `docs/README.claude-code.md` |\n| Cursor | `/add-plugin ...` | `docs/README.cursor.md` |\n| Codex | `/plugins` | `docs/README.codex.md` |\n| Copilot CLI | plugin install | `docs/README.copilot.md` |\n| Kimi Code | `/plugins install` | `docs/README.kimi.md` |\n| OpenCode | `plugin` array in opencode.json | `docs/README.opencode.md` |\n| pi | package install | `docs/README.pi.md` |\n| Gemini | `gemini extensions install` | `docs/README.gemini.md` |\n\nHow it works: at session start, `skills/using-fastmcp-engineering/SKILL.md` is\ninjected into the model context (wrapped in `<EXTREMELY_IMPORTANT>` + per-harness\ntool mapping), which makes the domain skills auto-trigger. Design:\n`docs/superpowers/specs/2026-09-01-fastmcp-superpowers-parity-design.md`.\n\n## Methodology Server (FastMCP v4, stdio)\n\nThis repository includes a FastMCP v4 server (`fastmcp.json` + `server/server.py`) that exposes the methodology as MCP resources, tools, and prompts over stdio.\n\n### Running the server\n\n```bash\nuv run fastmcp run fastmcp.json\n```\n\nThe server uses stdio transport and requires Python 3.12+ with `fastmcp>=4.0.0,<4.1` (managed via uv).\n\n### What the server exposes\n\n| Category | Items | Description |\n|----------|-------|-------------|\n| **Tools** | `find_skills`, `clarify_find` | Search 58 skills by task description with weighted ranking and session-aware domain boosting |\n| **Resources** | `skill://{name}/SKILL.md`, `skill://{name}/ACCEPTANCE.md`, `skill://{name}/_manifest` | 58 skills as versioned resources with content hashes |\n| **Resources** | `contract://{name}` | All contracts (e.g. `skill-contract`, `github-workflow-contract`) |\n| **Resources** | `fme-prompt://{name}` | All prompt templates from `prompts/` |\n| **Prompts** | `dispatch`, `skill_context`, `domain_guide`, `role_prompt`, `contract_check` | Reusable prompt templates for agent workflows |\n| **Completion** | Skills, contracts, prompts, domains | Tab-completion for prompt arguments and resource templates |\n| **Extension** | `methodology/stats` | Skill count, domains, and tool-call interceptor stats |\n| **Sessions** | `create_session`, `end_session` | Session lifecycle with `recent_domains` storage for history boost |\n\n### Per-harness install (stdio)\n\nThe server runs over stdio — configure each harness to launch it via `fastmcp run fastmcp.json`.\n\n**Claude Code** (`~/.claude/mcp_servers.json`):\n```json\n{\n  \"mcpServers\": {\n    \"fastmcp-engineering\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/fastmcp-engineering\", \"fastmcp\", \"run\", \"fastmcp.json\"],\n      \"transport\": \"stdio\"\n    }\n  }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"fastmcp-engineering\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/fastmcp-engineering\", \"fastmcp\", \"run\", \"fastmcp.json\"],\n      \"transport\": \"stdio\"\n    }\n  }\n}\n```\n\n**Codex** (`~/.codex/config.toml`):\n```toml\n[mcp_servers.fastmcp-engineering]\ncommand = \"uv\"\nargs = [\"run\", \"--directory\", \"/absolute/path/to/fastmcp-engineering\", \"fastmcp\", \"run\", \"fastmcp.json\"]\ntransport = \"stdio\"\n```\n\n**OpenCode** (`.opencode/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"fastmcp-engineering\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/fastmcp-engineering\", \"fastmcp\", \"run\", \"fastmcp.json\"],\n      \"transport\": \"stdio\"\n    }\n  }\n}\n```\n\n**Gemini** (`~/.gemini/settings.json`):\n```json\n{\n  \"mcpServers\": {\n    \"fastmcp-engineering\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/fastmcp-engineering\", \"fastmcp\", \"run\", \"fastmcp.json\"],\n      \"transport\": \"stdio\"\n    }\n  }\n}\n```\n\nReplace `/absolute/path/to/fastmcp-engineering` with the actual clone path. The `uv run --directory` ensures the server runs from the repo root so `skills/`, `contracts/`, and `prompts/` resolve correctly.\n\n### Example agent flow\n\n```python\nfrom fastmcp import Client\n\nasync with Client(\"fastmcp-engineering\") as client:\n    # 1. Find relevant skills for a task\n    skills = await client.call_tool(\"find_skills\", {\"task\": \"add OAuth to my FastMCP server\"})\n    top_skill = skills[0][\"name\"]  # e.g. \"fastmcp-auth\"\n\n    # 2. Read the full skill\n    skill = await client.read_resource(f\"skill://{top_skill}/SKILL.md\")\n\n    # 3. Get execution context prompt\n    context = await client.get_prompt(\"skill_context\", {\"skill\": top_skill})\n\n    # 4. Validate an artifact against a contract\n    check = await client.get_prompt(\"contract_check\", {\"contract\": \"skill-contract\", \"artifact\": \"...\"})\n```\n\nFull integration test: `tests/server/test_integration.py`.\n\n---\n\n## opencode integration\n\nGlobal exposure of this repository's capabilities in opencode:\n\n- **Skills**: global `skills.paths` → this clone (frontmatter `name`+`description` required)\n- **Reference**: `references.fastmcp-eng` — whole repo readable in any project\n- **Plugin hint**: `~/.config/opencode/plugin/fastmcp-engineering.ts` (verified PASS 2026-08-30)\n- **fm-* role agents**: `opencode/agents/` — research/implementation/audit/review/governor subagents; they load `prompts/<token>-<role>-agent.md` at runtime (auto-sync, no duplication)\n- **Commands**: `opencode/commands/` — `/fm` dispatcher, `/fm-prompts` inventory\n\nSetup on a new machine (symlinks into global config, run from repo root):\n\n    ln -s \"$PWD/opencode/agents/fm-research.md\" ~/.config/opencode/agents/fm-research.md\n    ln -s \"$PWD/opencode/agents/fm-implementation.md\" ~/.config/opencode/agents/fm-implementation.md\n    ln -s \"$PWD/opencode/agents/fm-audit.md\" ~/.config/opencode/agents/fm-audit.md\n    ln -s \"$PWD/opencode/agents/fm-review.md\" ~/.config/opencode/agents/fm-review.md\n    ln -s \"$PWD/opencode/agents/fm-governor.md\" ~/.config/opencode/agents/fm-governor.md\n    ln -s \"$PWD/opencode/commands/fm.md\" ~/.config/opencode/commands/fm.md\n    ln -s \"$PWD/opencode/commands/fm-prompts.md\" ~/.config/opencode/commands/fm-prompts.md\n\nDesign: `docs/superpowers/specs/2026-08-31-opencode-fastmcp-maximal-design.md`\n",
  "bytes": 8972,
  "sha": "e7ebc40d336f86ff7dfb3b979e6806faa8ff9f893a7ba0ead036957f3300a23a",
  "repo_slug": "evgenygurin/fastmcp-engineering",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_evgenygurin_fastmcp_engineering_0fe45c8c/readme"
}