[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6FGGGW2AFHT95YHRRHZEN5M":3,"skill-same:01M6FGGGW2AFHT95YHRRHZEN5M":148},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":25,"publishedAt":26,"linkOnly":27,"markdownContent":28,"markdownBody":29,"frontMatter":30,"refName":31,"commitSha":32,"skillDirectory":33,"forksCount":34,"repositoryHtmlUrl":35,"repositoryHomepageUrl":36,"ownerHtmlUrl":37,"ownerBlogUrl":6,"ownerDescription":38,"updatedAt":39,"install":40,"resources":53},"01M6FGGGW2AFHT95YHRRHZEN5M","fastmcp",null,"ComeOnOliver\u002Fskillshub","ComeOnOliver","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43215937?v=4","01M6E5JNFECJAAVFE0W7SMWWD2","Haoran Shu","01M6E5JNNDQS7AJZDYFQ8TPZCK",66,"MIT","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",[5],"2026-11-10 10:12:30",false,"---\nname: fastmcp\ndescription: FastMCP Python framework for MCP servers with tools, resources, storage backends (memory\u002Fdisk\u002FRedis\u002FDynamoDB). Use for Claude tool exposure, OAuth Proxy, cloud deployment, or encountering storage, lifespan, middleware, circular import, async errors.\n\n  Keywords: FastMCP, MCP server Python, Model Context Protocol Python, fastmcp framework, mcp tools, mcp resources, mcp prompts, fastmcp storage, fastmcp memory storage, fastmcp disk storage, fastmcp redis, fastmcp dynamodb, fastmcp lifespan, fastmcp middleware, fastmcp oauth proxy, server composition mcp, fastmcp import, fastmcp mount, fastmcp cloud, fastmcp deployment, mcp authentication, fastmcp icons, openapi mcp, claude mcp server, fastmcp testing, storage misconfiguration, lifespan issues, middleware order, circular imports, module-level server, async await mcp\nlicense: MIT\nmetadata:\n  version: \"2.0.0\"\n  package_version: \"fastmcp>=2.13.0\"\n  python_version: \">=3.10\"\n  token_savings: \"90-95%\"\n  errors_prevented: 25\n  production_tested: true\n  last_updated: \"2025-11-18\"\n---\n\n# FastMCP - Build MCP Servers in Python\n\nFastMCP is a Python framework for building Model Context Protocol (MCP) servers that expose tools, resources, and prompts to Large Language Models like Claude.\n\n## Quick Start\n\n### Installation\n\n```bash\npip install fastmcp\n# or: uv pip install fastmcp\n```\n\n### Minimal Server\n\n```python\nfrom fastmcp import FastMCP\n\n# MUST be at module level for FastMCP Cloud\nmcp = FastMCP(\"My Server\")\n\n@mcp.tool()\nasync def hello(name: str) -> str:\n    \"\"\"Say hello to someone.\"\"\"\n    return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\n**Run:**\n```bash\npython server.py              # Local development\nfastmcp dev server.py         # With FastMCP CLI\npython server.py --transport http --port 8000  # HTTP mode\n```\n\n**Copy-Paste Template**: See `templates\u002Fbasic-server.py`\n\n## Core Concepts\n\n### Tools\n\nFunctions that LLMs can call:\n\n```python\n@mcp.tool()\ndef calculate(operation: str, a: float, b: float) -> float:\n    \"\"\"Perform mathematical operations.\"\"\"\n    operations = {\n        \"add\": lambda x, y: x + y,\n        \"subtract\": lambda x, y: x - y,\n        \"multiply\": lambda x, y: x * y,\n        \"divide\": lambda x, y: x \u002F y if y != 0 else None\n    }\n    return operations.get(operation, lambda x, y: None)(a, b)\n```\n\n**Best Practices:**\n- Clear, descriptive function names\n- Comprehensive docstrings (LLMs read these!)\n- Strong type hints (Pydantic validates automatically)\n- Return structured data (dicts\u002Flists)\n- Handle errors gracefully\n\n### Resources\n\nExpose static or dynamic data:\n\n```python\n@mcp.resource(\"data:\u002F\u002Fconfig\")\ndef get_config() -> dict:\n    \"\"\"Provide application configuration.\"\"\"\n    return {\"version\": \"1.0.0\", \"features\": [\"auth\", \"api\"]}\n\n# Dynamic resource with parameters\n@mcp.resource(\"user:\u002F\u002F{user_id}\u002Fprofile\")\nasync def get_user_profile(user_id: str) -> dict:\n    \"\"\"Get user profile by ID.\"\"\"\n    return {\"id\": user_id, \"name\": f\"User {user_id}\"}\n```\n\n**URI Schemes**: `data:\u002F\u002F`, `file:\u002F\u002F`, `resource:\u002F\u002F`, `info:\u002F\u002F`, `api:\u002F\u002F`, or custom\n\n### Prompts\n\nPre-configured prompts for LLMs:\n\n```python\n@mcp.prompt(\"analyze\")\ndef analyze_prompt(topic: str) -> str:\n    \"\"\"Generate analysis prompt.\"\"\"\n    return f\"\"\"Analyze {topic} considering:\n    1. Current state\n    2. Challenges\n    3. Opportunities\n    4. Recommendations\"\"\"\n```\n\n### Context Features\n\n**Progress Tracking:**\n```python\nfrom fastmcp import Context\n\n@mcp.tool()\nasync def batch_process(items: list, context: Context) -> dict:\n    \"\"\"Process items with progress updates.\"\"\"\n    for i, item in enumerate(items):\n        await context.report_progress(i + 1, len(items), f\"Processing {item}\")\n        await process_item(item)\n    return {\"processed\": len(items)}\n```\n\n**User Input:**\n```python\n@mcp.tool()\nasync def confirm_action(action: str, context: Context) -> dict:\n    \"\"\"Perform action with user confirmation.\"\"\"\n    confirmed = await context.request_elicitation(\n        prompt=f\"Confirm {action}? (yes\u002Fno)\",\n        response_type=str\n    )\n    return {\"confirmed\": confirmed.lower() == \"yes\"}\n```\n\n## Storage Backends\n\nChoose storage based on deployment:\n\n```python\nfrom key_value.stores import DiskStore, RedisStore\nfrom key_value.encryption import FernetEncryptionWrapper\nfrom cryptography.fernet import Fernet\n\n# Memory (default) - Development only\nmcp = FastMCP(\"Dev Server\")\n\n# Disk - Single instance\nmcp = FastMCP(\n    \"Production Server\",\n    storage=FernetEncryptionWrapper(\n        key_value=DiskStore(path=\"\u002Fvar\u002Flib\u002Fmcp\u002Fstorage\"),\n        fernet=Fernet(os.getenv(\"STORAGE_ENCRYPTION_KEY\"))\n    )\n)\n\n# Redis - Multi-instance\nmcp = FastMCP(\n    \"Production Server\",\n    storage=FernetEncryptionWrapper(\n        key_value=RedisStore(\n            host=os.getenv(\"REDIS_HOST\"),\n            password=os.getenv(\"REDIS_PASSWORD\")\n        ),\n        fernet=Fernet(os.getenv(\"STORAGE_ENCRYPTION_KEY\"))\n    )\n)\n```\n\n## Server Lifespans\n\nInitialize resources on server startup:\n\n```python\nfrom contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def app_lifespan(server: FastMCP):\n    \"\"\"Runs ONCE when server starts (v2.13.0+).\"\"\"\n    db = await Database.connect()\n    print(\"Server starting\")\n    \n    try:\n        yield {\"db\": db}\n    finally:\n        await db.disconnect()\n        print(\"Server stopping\")\n\nmcp = FastMCP(\"My Server\", lifespan=app_lifespan)\n```\n\n**Critical**: v2.13.0+ lifespans run per-server (not per-session). For per-session logic, use middleware.\n\n## Middleware System\n\n8 built-in middleware types:\n\n```python\nfrom fastmcp.middleware import (\n    LoggingMiddleware,\n    TimingMiddleware,\n    RateLimitingMiddleware,\n    ResponseCachingMiddleware\n)\n\n# Order matters!\nmcp.add_middleware(LoggingMiddleware())\nmcp.add_middleware(TimingMiddleware())\nmcp.add_middleware(RateLimitingMiddleware(max_requests=100, window_seconds=60))\nmcp.add_middleware(ResponseCachingMiddleware(ttl_seconds=3600))\n```\n\n**Custom Middleware:**\n```python\nfrom fastmcp.middleware import BaseMiddleware\n\nclass CustomMiddleware(BaseMiddleware):\n    async def on_call_tool(self, tool_name, arguments, context):\n        print(f\"Before: {tool_name}\")\n        result = await self.next(tool_name, arguments, context)  # MUST call next()\n        print(f\"After: {tool_name}\")\n        return result\n```\n\n## Server Composition\n\n**Import Server** (static, one-time copy):\n```python\nmain_server.import_server(vendor_server)  # Static bundle\n```\n\n**Mount Server** (dynamic, runtime delegation):\n```python\nmain_server.mount(api_server, prefix=\"api\")  # Changes appear immediately\n```\n\n## Cloud Deployment\n\n**FastMCP Cloud Requirements:**\n1. Server MUST be at module level\n2. Use disk\u002FRedis storage (not memory)\n3. No import-time execution\n\n```python\n# ✅ Cloud-ready pattern\nmcp = FastMCP(\"My Server\")  # Module level\n\n@mcp.tool()\nasync def my_tool(): pass\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\n**Deploy:**\n```bash\nfastmcp deploy server.py\n```\n\n## Top 5 Critical Errors\n\n### 1. Missing Server Object\n\n**Error:** `RuntimeError: No server object found at module level`\n\n**Fix:**\n```python\n# ❌ WRONG\ndef create_server():\n    return FastMCP(\"server\")\n\n# ✅ CORRECT\nmcp = FastMCP(\"server\")  # At module level\n```\n\n### 2. Async\u002FAwait Confusion\n\n**Error:** `RuntimeError: no running event loop`\n\n**Fix:**\n```python\n# ❌ WRONG: Sync function calling async\n@mcp.tool()\ndef bad_tool():\n    result = await async_function()  # Error!\n\n# ✅ CORRECT: Async tool\n@mcp.tool()\nasync def good_tool():\n    result = await async_function()\n    return result\n```\n\n### 3. Context Not Injected\n\n**Error:** `TypeError: missing 1 required positional argument: 'context'`\n\n**Fix:**\n```python\nfrom fastmcp import Context\n\n# ❌ WRONG: No type hint\n@mcp.tool()\nasync def bad_tool(context):  # Missing type!\n    await context.report_progress(...)\n\n# ✅ CORRECT: Proper type hint\n@mcp.tool()\nasync def good_tool(context: Context):\n    await context.report_progress(0, 100, \"Starting\")\n```\n\n### 4. Storage Backend Not Configured\n\n**Error:** `RuntimeError: OAuth tokens lost on restart`\n\n**Fix:** Use disk or Redis storage in production (see Storage Backends section above)\n\n### 5. Circular Import Errors\n\n**Error:** `ImportError: cannot import name 'X' from partially initialized module`\n\n**Fix:**\n```python\n# ❌ WRONG: Factory function creating circular dependency\n# shared\u002F__init__.py\ndef get_client():\n    from .api_client import APIClient  # Circular!\n    return APIClient()\n\n# ✅ CORRECT: Direct imports\n# shared\u002F__init__.py\nfrom .api_client import APIClient\nfrom .cache import CacheManager\n\n# shared\u002Fmonitoring.py\nfrom .api_client import APIClient\nclient = APIClient()\n```\n\n**See all 25 errors**: `references\u002Ferror-catalog.md`\n\n## Client Configuration\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"python\",\n      \"args\": [\"\u002Fpath\u002Fto\u002Fserver.py\"]\n    }\n  }\n}\n```\n\n### Claude Code CLI\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"python\",\n      \"args\": [\"server.py\"]\n    }\n  }\n}\n```\n\n## CLI Commands\n\n```bash\nfastmcp dev server.py              # Development mode with hot reload\nfastmcp run server.py              # Production mode\nfastmcp deploy server.py           # Deploy to FastMCP Cloud\nfastmcp test server.py             # Run tests\n```\n\n## Best Practices\n\n1. **Server Structure**: Keep module-level server, organize tools in separate files\n2. **Type Hints**: Use Pydantic models for complex validation\n3. **Documentation**: Write detailed docstrings (LLMs read them!)\n4. **Error Handling**: Catch and return structured errors\n5. **Storage**: Use encrypted disk\u002FRedis in production\n6. **Lifespans**: Initialize connections once per server\n7. **Middleware**: Order matters (error handling → timing → logging → rate limiting → caching)\n8. **Testing**: Unit test tools with `FastMCP.test_tool()`\n\n## Bundled Resources\n\n**References** (`references\u002F`):\n- `cli-commands.md` - Complete CLI command reference (dev, run, deploy, test)\n- `cloud-deployment.md` - FastMCP Cloud deployment guide with module-level requirements\n- `common-errors.md` - All 25 documented errors with solutions and prevention\n- `context-features.md` - Progress tracking, user input, and Context API patterns\n- `error-catalog.md` - Comprehensive error catalog with fixes\n- `integration-patterns.md` - Server composition (import\u002Fmount), OAuth Proxy, OpenAPI\n- `production-patterns.md` - Storage backends, lifespans, middleware, architecture patterns\n\n**Templates** (`templates\u002F`):\n- `basic-server.py` - Minimal MCP server with tools, resources, prompts\n- `client-example.py` - MCP client integration examples\n- `api-client-pattern.py` - API integration patterns\n- `error-handling.py` - Error handling best practices\n- `openapi-integration.py` - OpenAPI schema integration\n- `prompts-examples.py` - Prompt template patterns\n- `resources-examples.py` - Resource URI patterns and examples\n- `tools-examples.py` - Tool definition patterns\n- `self-contained-server.py` - Complete production-ready self-contained server\n- `.env.example` - Environment variables template\n- `requirements.txt` - Python dependencies\n- `pyproject.toml` - Python project configuration\n\n## Dependencies\n\n```json\n{\n  \"dependencies\": {\n    \"fastmcp\": \">=2.13.0\",\n    \"pydantic\": \">=2.0.0\"\n  },\n  \"optionalDependencies\": {\n    \"py-key-value-aio\": \">=0.1.0\",  \u002F\u002F For storage backends\n    \"cryptography\": \">=41.0.0\",     \u002F\u002F For encryption\n    \"redis\": \">=5.0.0\"              \u002F\u002F For Redis storage\n  }\n}\n```\n\n## Official Documentation\n\n- FastMCP GitHub: https:\u002F\u002Fgithub.com\u002Fjlowin\u002Ffastmcp\n- MCP Protocol: https:\u002F\u002Fmodelcontextprotocol.io\n- FastMCP Cloud: https:\u002F\u002Ffastmcp.com\n\n## Verification Checklist\n\n- [ ] FastMCP installed (`fastmcp>=2.13.0`)\n- [ ] Server object at module level\n- [ ] Tool docstrings comprehensive\n- [ ] Context type hints for context parameters\n- [ ] Resource URIs have schemes\n- [ ] Storage backend configured (production)\n- [ ] Lifespan pattern correct (v2.13.0+)\n- [ ] Middleware order logical\n- [ ] Client configuration tested\n- [ ] Production deployment successful\n\n**Token Savings**: 90-95% vs learning from scratch\n**Errors Prevented**: 25 documented issues\n**Production Tested**: ✅ Multiple deployments\n","# FastMCP - Build MCP Servers in Python\n\nFastMCP is a Python framework for building Model Context Protocol (MCP) servers that expose tools, resources, and prompts to Large Language Models like Claude.\n\n## Quick Start\n\n### Installation\n\n```bash\npip install fastmcp\n# or: uv pip install fastmcp\n```\n\n### Minimal Server\n\n```python\nfrom fastmcp import FastMCP\n\n# MUST be at module level for FastMCP Cloud\nmcp = FastMCP(\"My Server\")\n\n@mcp.tool()\nasync def hello(name: str) -> str:\n    \"\"\"Say hello to someone.\"\"\"\n    return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\n**Run:**\n```bash\npython server.py              # Local development\nfastmcp dev server.py         # With FastMCP CLI\npython server.py --transport http --port 8000  # HTTP mode\n```\n\n**Copy-Paste Template**: See `templates\u002Fbasic-server.py`\n\n## Core Concepts\n\n### Tools\n\nFunctions that LLMs can call:\n\n```python\n@mcp.tool()\ndef calculate(operation: str, a: float, b: float) -> float:\n    \"\"\"Perform mathematical operations.\"\"\"\n    operations = {\n        \"add\": lambda x, y: x + y,\n        \"subtract\": lambda x, y: x - y,\n        \"multiply\": lambda x, y: x * y,\n        \"divide\": lambda x, y: x \u002F y if y != 0 else None\n    }\n    return operations.get(operation, lambda x, y: None)(a, b)\n```\n\n**Best Practices:**\n- Clear, descriptive function names\n- Comprehensive docstrings (LLMs read these!)\n- Strong type hints (Pydantic validates automatically)\n- Return structured data (dicts\u002Flists)\n- Handle errors gracefully\n\n### Resources\n\nExpose static or dynamic data:\n\n```python\n@mcp.resource(\"data:\u002F\u002Fconfig\")\ndef get_config() -> dict:\n    \"\"\"Provide application configuration.\"\"\"\n    return {\"version\": \"1.0.0\", \"features\": [\"auth\", \"api\"]}\n\n# Dynamic resource with parameters\n@mcp.resource(\"user:\u002F\u002F{user_id}\u002Fprofile\")\nasync def get_user_profile(user_id: str) -> dict:\n    \"\"\"Get user profile by ID.\"\"\"\n    return {\"id\": user_id, \"name\": f\"User {user_id}\"}\n```\n\n**URI Schemes**: `data:\u002F\u002F`, `file:\u002F\u002F`, `resource:\u002F\u002F`, `info:\u002F\u002F`, `api:\u002F\u002F`, or custom\n\n### Prompts\n\nPre-configured prompts for LLMs:\n\n```python\n@mcp.prompt(\"analyze\")\ndef analyze_prompt(topic: str) -> str:\n    \"\"\"Generate analysis prompt.\"\"\"\n    return f\"\"\"Analyze {topic} considering:\n    1. Current state\n    2. Challenges\n    3. Opportunities\n    4. Recommendations\"\"\"\n```\n\n### Context Features\n\n**Progress Tracking:**\n```python\nfrom fastmcp import Context\n\n@mcp.tool()\nasync def batch_process(items: list, context: Context) -> dict:\n    \"\"\"Process items with progress updates.\"\"\"\n    for i, item in enumerate(items):\n        await context.report_progress(i + 1, len(items), f\"Processing {item}\")\n        await process_item(item)\n    return {\"processed\": len(items)}\n```\n\n**User Input:**\n```python\n@mcp.tool()\nasync def confirm_action(action: str, context: Context) -> dict:\n    \"\"\"Perform action with user confirmation.\"\"\"\n    confirmed = await context.request_elicitation(\n        prompt=f\"Confirm {action}? (yes\u002Fno)\",\n        response_type=str\n    )\n    return {\"confirmed\": confirmed.lower() == \"yes\"}\n```\n\n## Storage Backends\n\nChoose storage based on deployment:\n\n```python\nfrom key_value.stores import DiskStore, RedisStore\nfrom key_value.encryption import FernetEncryptionWrapper\nfrom cryptography.fernet import Fernet\n\n# Memory (default) - Development only\nmcp = FastMCP(\"Dev Server\")\n\n# Disk - Single instance\nmcp = FastMCP(\n    \"Production Server\",\n    storage=FernetEncryptionWrapper(\n        key_value=DiskStore(path=\"\u002Fvar\u002Flib\u002Fmcp\u002Fstorage\"),\n        fernet=Fernet(os.getenv(\"STORAGE_ENCRYPTION_KEY\"))\n    )\n)\n\n# Redis - Multi-instance\nmcp = FastMCP(\n    \"Production Server\",\n    storage=FernetEncryptionWrapper(\n        key_value=RedisStore(\n            host=os.getenv(\"REDIS_HOST\"),\n            password=os.getenv(\"REDIS_PASSWORD\")\n        ),\n        fernet=Fernet(os.getenv(\"STORAGE_ENCRYPTION_KEY\"))\n    )\n)\n```\n\n## Server Lifespans\n\nInitialize resources on server startup:\n\n```python\nfrom contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def app_lifespan(server: FastMCP):\n    \"\"\"Runs ONCE when server starts (v2.13.0+).\"\"\"\n    db = await Database.connect()\n    print(\"Server starting\")\n    \n    try:\n        yield {\"db\": db}\n    finally:\n        await db.disconnect()\n        print(\"Server stopping\")\n\nmcp = FastMCP(\"My Server\", lifespan=app_lifespan)\n```\n\n**Critical**: v2.13.0+ lifespans run per-server (not per-session). For per-session logic, use middleware.\n\n## Middleware System\n\n8 built-in middleware types:\n\n```python\nfrom fastmcp.middleware import (\n    LoggingMiddleware,\n    TimingMiddleware,\n    RateLimitingMiddleware,\n    ResponseCachingMiddleware\n)\n\n# Order matters!\nmcp.add_middleware(LoggingMiddleware())\nmcp.add_middleware(TimingMiddleware())\nmcp.add_middleware(RateLimitingMiddleware(max_requests=100, window_seconds=60))\nmcp.add_middleware(ResponseCachingMiddleware(ttl_seconds=3600))\n```\n\n**Custom Middleware:**\n```python\nfrom fastmcp.middleware import BaseMiddleware\n\nclass CustomMiddleware(BaseMiddleware):\n    async def on_call_tool(self, tool_name, arguments, context):\n        print(f\"Before: {tool_name}\")\n        result = await self.next(tool_name, arguments, context)  # MUST call next()\n        print(f\"After: {tool_name}\")\n        return result\n```\n\n## Server Composition\n\n**Import Server** (static, one-time copy):\n```python\nmain_server.import_server(vendor_server)  # Static bundle\n```\n\n**Mount Server** (dynamic, runtime delegation):\n```python\nmain_server.mount(api_server, prefix=\"api\")  # Changes appear immediately\n```\n\n## Cloud Deployment\n\n**FastMCP Cloud Requirements:**\n1. Server MUST be at module level\n2. Use disk\u002FRedis storage (not memory)\n3. No import-time execution\n\n```python\n# ✅ Cloud-ready pattern\nmcp = FastMCP(\"My Server\")  # Module level\n\n@mcp.tool()\nasync def my_tool(): pass\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\n**Deploy:**\n```bash\nfastmcp deploy server.py\n```\n\n## Top 5 Critical Errors\n\n### 1. Missing Server Object\n\n**Error:** `RuntimeError: No server object found at module level`\n\n**Fix:**\n```python\n# ❌ WRONG\ndef create_server():\n    return FastMCP(\"server\")\n\n# ✅ CORRECT\nmcp = FastMCP(\"server\")  # At module level\n```\n\n### 2. Async\u002FAwait Confusion\n\n**Error:** `RuntimeError: no running event loop`\n\n**Fix:**\n```python\n# ❌ WRONG: Sync function calling async\n@mcp.tool()\ndef bad_tool():\n    result = await async_function()  # Error!\n\n# ✅ CORRECT: Async tool\n@mcp.tool()\nasync def good_tool():\n    result = await async_function()\n    return result\n```\n\n### 3. Context Not Injected\n\n**Error:** `TypeError: missing 1 required positional argument: 'context'`\n\n**Fix:**\n```python\nfrom fastmcp import Context\n\n# ❌ WRONG: No type hint\n@mcp.tool()\nasync def bad_tool(context):  # Missing type!\n    await context.report_progress(...)\n\n# ✅ CORRECT: Proper type hint\n@mcp.tool()\nasync def good_tool(context: Context):\n    await context.report_progress(0, 100, \"Starting\")\n```\n\n### 4. Storage Backend Not Configured\n\n**Error:** `RuntimeError: OAuth tokens lost on restart`\n\n**Fix:** Use disk or Redis storage in production (see Storage Backends section above)\n\n### 5. Circular Import Errors\n\n**Error:** `ImportError: cannot import name 'X' from partially initialized module`\n\n**Fix:**\n```python\n# ❌ WRONG: Factory function creating circular dependency\n# shared\u002F__init__.py\ndef get_client():\n    from .api_client import APIClient  # Circular!\n    return APIClient()\n\n# ✅ CORRECT: Direct imports\n# shared\u002F__init__.py\nfrom .api_client import APIClient\nfrom .cache import CacheManager\n\n# shared\u002Fmonitoring.py\nfrom .api_client import APIClient\nclient = APIClient()\n```\n\n**See all 25 errors**: `references\u002Ferror-catalog.md`\n\n## Client Configuration\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"python\",\n      \"args\": [\"\u002Fpath\u002Fto\u002Fserver.py\"]\n    }\n  }\n}\n```\n\n### Claude Code CLI\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"python\",\n      \"args\": [\"server.py\"]\n    }\n  }\n}\n```\n\n## CLI Commands\n\n```bash\nfastmcp dev server.py              # Development mode with hot reload\nfastmcp run server.py              # Production mode\nfastmcp deploy server.py           # Deploy to FastMCP Cloud\nfastmcp test server.py             # Run tests\n```\n\n## Best Practices\n\n1. **Server Structure**: Keep module-level server, organize tools in separate files\n2. **Type Hints**: Use Pydantic models for complex validation\n3. **Documentation**: Write detailed docstrings (LLMs read them!)\n4. **Error Handling**: Catch and return structured errors\n5. **Storage**: Use encrypted disk\u002FRedis in production\n6. **Lifespans**: Initialize connections once per server\n7. **Middleware**: Order matters (error handling → timing → logging → rate limiting → caching)\n8. **Testing**: Unit test tools with `FastMCP.test_tool()`\n\n## Bundled Resources\n\n**References** (`references\u002F`):\n- `cli-commands.md` - Complete CLI command reference (dev, run, deploy, test)\n- `cloud-deployment.md` - FastMCP Cloud deployment guide with module-level requirements\n- `common-errors.md` - All 25 documented errors with solutions and prevention\n- `context-features.md` - Progress tracking, user input, and Context API patterns\n- `error-catalog.md` - Comprehensive error catalog with fixes\n- `integration-patterns.md` - Server composition (import\u002Fmount), OAuth Proxy, OpenAPI\n- `production-patterns.md` - Storage backends, lifespans, middleware, architecture patterns\n\n**Templates** (`templates\u002F`):\n- `basic-server.py` - Minimal MCP server with tools, resources, prompts\n- `client-example.py` - MCP client integration examples\n- `api-client-pattern.py` - API integration patterns\n- `error-handling.py` - Error handling best practices\n- `openapi-integration.py` - OpenAPI schema integration\n- `prompts-examples.py` - Prompt template patterns\n- `resources-examples.py` - Resource URI patterns and examples\n- `tools-examples.py` - Tool definition patterns\n- `self-contained-server.py` - Complete production-ready self-contained server\n- `.env.example` - Environment variables template\n- `requirements.txt` - Python dependencies\n- `pyproject.toml` - Python project configuration\n\n## Dependencies\n\n```json\n{\n  \"dependencies\": {\n    \"fastmcp\": \">=2.13.0\",\n    \"pydantic\": \">=2.0.0\"\n  },\n  \"optionalDependencies\": {\n    \"py-key-value-aio\": \">=0.1.0\",  \u002F\u002F For storage backends\n    \"cryptography\": \">=41.0.0\",     \u002F\u002F For encryption\n    \"redis\": \">=5.0.0\"              \u002F\u002F For Redis storage\n  }\n}\n```\n\n## Official Documentation\n\n- FastMCP GitHub: https:\u002F\u002Fgithub.com\u002Fjlowin\u002Ffastmcp\n- MCP Protocol: https:\u002F\u002Fmodelcontextprotocol.io\n- FastMCP Cloud: https:\u002F\u002Ffastmcp.com\n\n## Verification Checklist\n\n- [ ] FastMCP installed (`fastmcp>=2.13.0`)\n- [ ] Server object at module level\n- [ ] Tool docstrings comprehensive\n- [ ] Context type hints for context parameters\n- [ ] Resource URIs have schemes\n- [ ] Storage backend configured (production)\n- [ ] Lifespan pattern correct (v2.13.0+)\n- [ ] Middleware order logical\n- [ ] Client configuration tested\n- [ ] Production deployment successful\n\n**Token Savings**: 90-95% vs learning from scratch\n**Errors Prevented**: 25 documented issues\n**Production Tested**: ✅ Multiple deployments\n",{},"main","def8531e65114c0fca8fb8551c1871ee0eed705c","skills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp",24,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub","https:\u002F\u002Fskillshub.wtf","https:\u002F\u002Fgithub.com\u002FComeOnOliver","AI & Blockchain Engineer\r\n","2026-06-24 22:07:19",{"source":7,"skillName":5,"commands":41,"prompt":51,"zipAvailable":52},[42,45,48],{"tool":43,"command":44},"npx","npx skills add ComeOnOliver\u002Fskillshub --skill fastmcp",{"tool":46,"command":47},"bunx","bunx skills add ComeOnOliver\u002Fskillshub --skill fastmcp",{"tool":49,"command":50},"pnpm","pnpm dlx skills add ComeOnOliver\u002Fskillshub --skill fastmcp","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002FSKILL.md",true,[54,60,64,68,72,76,80,84,90,94,98,104,108,112,116,120,124,128,132,136,140,144],{"path":55,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fcli-commands.md","REFERENCE","参考文档",7130,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Freferences\u002Fcli-commands.md",{"path":61,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":62,"sourceHtmlUrl":63},"references\u002Fcloud-deployment.md",6434,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Freferences\u002Fcloud-deployment.md",{"path":65,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":66,"sourceHtmlUrl":67},"references\u002Fcommon-errors.md",4752,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Freferences\u002Fcommon-errors.md",{"path":69,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Fcontext-features.md",12261,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Freferences\u002Fcontext-features.md",{"path":73,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Ferror-catalog.md",18672,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Freferences\u002Ferror-catalog.md",{"path":77,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":78,"sourceHtmlUrl":79},"references\u002Fintegration-patterns.md",11128,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Freferences\u002Fintegration-patterns.md",{"path":81,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":82,"sourceHtmlUrl":83},"references\u002Fproduction-patterns.md",12410,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Freferences\u002Fproduction-patterns.md",{"path":85,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":88,"sourceHtmlUrl":89},"scripts\u002Fcheck-versions.sh","SCRIPT","脚本",2971,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Fscripts\u002Fcheck-versions.sh",{"path":91,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":92,"sourceHtmlUrl":93},"scripts\u002Fdeploy-cloud.sh",6941,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Fscripts\u002Fdeploy-cloud.sh",{"path":95,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":96,"sourceHtmlUrl":97},"scripts\u002Ftest-server.sh",5293,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Fscripts\u002Ftest-server.sh",{"path":99,"resourceType":100,"resourceTypeDesc":101,"sizeBytes":102,"sourceHtmlUrl":103},"templates\u002F.env.example","OTHER","其他",1320,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002F.env.example",{"path":105,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":106,"sourceHtmlUrl":107},"templates\u002Fapi-client-pattern.py",11626,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Fapi-client-pattern.py",{"path":109,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":110,"sourceHtmlUrl":111},"templates\u002Fbasic-server.py",1876,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Fbasic-server.py",{"path":113,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":114,"sourceHtmlUrl":115},"templates\u002Fclient-example.py",10202,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Fclient-example.py",{"path":117,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":118,"sourceHtmlUrl":119},"templates\u002Ferror-handling.py",11268,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Ferror-handling.py",{"path":121,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":122,"sourceHtmlUrl":123},"templates\u002Fopenapi-integration.py",7727,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Fopenapi-integration.py",{"path":125,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":126,"sourceHtmlUrl":127},"templates\u002Fprompts-examples.py",8265,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Fprompts-examples.py",{"path":129,"resourceType":100,"resourceTypeDesc":101,"sizeBytes":130,"sourceHtmlUrl":131},"templates\u002Fpyproject.toml",2007,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Fpyproject.toml",{"path":133,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":134,"sourceHtmlUrl":135},"templates\u002Frequirements.txt",434,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Frequirements.txt",{"path":137,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":138,"sourceHtmlUrl":139},"templates\u002Fresources-examples.py",6364,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Fresources-examples.py",{"path":141,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":142,"sourceHtmlUrl":143},"templates\u002Fself-contained-server.py",11865,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Fself-contained-server.py",{"path":145,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":146,"sourceHtmlUrl":147},"templates\u002Ftools-examples.py",6233,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Ffastmcp\u002Ftemplates\u002Ftools-examples.py",[149,159,169,178,184,191],{"skillNo":150,"name":151,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":152,"categories":153,"keywords":155,"publishedAt":26},"01M6FKJN13GMG4KY57J3QD8GY5","model-hierarchy-skill","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzscole\u002Fmodel-hierarchy-skill\u002Fmodel-hierarchy-skill\u002FSKILL.md",[154],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[156,157,158],"model","model hierarchy","model hierarchy skill",{"skillNo":160,"name":161,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":162,"categories":163,"keywords":165,"publishedAt":26},"01M6FKJJJ6GCAMR4PPPRD12M5X","zoom-mcp","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-mcp\u002FSKILL.md",[164],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[166,167,168],"MCP","zoom","zoom mcp",{"skillNo":170,"name":171,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":172,"categories":173,"keywords":174,"publishedAt":26},"01M6FKJE3KYT3KPEZMEEHYKA6K","zoom-apps-sdk","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-apps-sdk\u002FSKILL.md",[],[175,176,177,167],"sdk","zoom apps sdk","apps",{"skillNo":179,"name":180,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":181,"categories":182,"keywords":183,"publishedAt":26},"01M6FKJ9EDH9Q5VWDF8HAJRSP0","windows","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwindows\u002FSKILL.md",[],[180],{"skillNo":185,"name":186,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":187,"categories":188,"keywords":190,"publishedAt":26},"01M6FKJ666BEEFC3AE9GJ72Q93","whiteboard","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwhiteboard\u002FSKILL.md",[189],{"categoryNo":23,"categoryName":24,"taxonomyType":20,"taxonomyTypeDesc":21},[186],{"skillNo":192,"name":193,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":194,"categories":195,"keywords":196,"publishedAt":26},"01M6FKJ21WFCDGTJQ2Q91T9DVW","websockets","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwebsockets\u002FSKILL.md",[],[193]]