⚡ FastMCP TypeScript — Agent Skill

An AI agent skill that helps LLMs write correct FastMCP TypeScript code — no more hallucinated APIs, wrong imports, or broken patterns.

The Problem

FastMCP (punkpeye/fastmcp) is a TypeScript framework for building MCP servers. However, AI agents frequently:

• ❌ Confuse it with the official MCP SDK (@modelcontextprotocol/sdk) and use server.registerTool() instead of server.addTool()
• ❌ Confuse it with Python FastMCP (pip install fastmcp) and generate decorator-based code
• ❌ Return raw objects from execute instead of strings or { content: [...] }
• ❌ Use console.log inside tools (corrupts stdio transport)
• ❌ Set up Express manually instead of using built-in httpStream transport
• ❌ Miss .describe() on Zod fields, making tools unusable by LLMs

This skill fixes all of that.

What's Included

File	Covers
SKILL.md	Entry point — setup, server init, core API quick-reference, when to load each reference
tools.md	Tool implementation — return types, streaming, progress reporting, annotations, authorization
resources.md	Resources & resource templates — URIs, MIME types, embedded resources
prompts.md	Prompts — arguments, auto-completion, multi-step prompts
auth.md	Authentication — OAuth providers (Google, GitHub, Azure), API keys, custom auth
transport.md	Transport — HTTP streaming, SSE, stdio, stateless mode, Cloudflare Workers (Edge)
anti_patterns.md	Anti-patterns & common mistakes — the most critical file for preventing hallucination

How to Use

As a Cursor / Windsurf / Roo Skill

Drop the files into your project's skill directory:

your-project/
  skills/
    fastmcp-ts/
      SKILL.md
      tools.md
      resources.md
      prompts.md
      auth.md
      transport.md
      anti_patterns.md

Your AI agent will automatically load SKILL.md when it detects FastMCP-related work and pull in the relevant reference files as needed.

As a CLAUDE.md

Concatenate the key files into a CLAUDE.md at your project root:

cat SKILL.md anti_patterns.md > CLAUDE.md

As General Reference

Read through anti_patterns.md first — it covers the 11 most common mistakes agents and developers make with FastMCP TypeScript.

Compatibility

• FastMCP v3.x (npm: fastmcp)
• Node.js 18+
• TypeScript with ES2022 target and NodeNext module resolution
• Works with any AI coding agent that supports skill files (Cursor, Windsurf, Roo, Claude Code, etc.)

Why This Exists

The Python FastMCP has excellent, detailed documentation. The TypeScript version (punkpeye/fastmcp) is powerful but its docs are thinner — which causes AI agents to hallucinate patterns from the official SDK or the Python version. This skill bridges that gap by giving agents precise, correct API references tuned specifically for FastMCP TypeScript.

Contributing

Found an incorrect pattern or a new anti-pattern? PRs are welcome! Please include:

• A ❌ wrong example showing what agents get wrong
• A ✅ correct example with the proper FastMCP TypeScript pattern

License

MIT