{"record":{"id":"fc39e5b87bad058c","repo":"datawhalechina/hello-agents","slug":"mcp-fastmcp-pip-install-fastmcp","errorCode":null,"errorMessage":"创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp","messagePattern":"创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"Co-creation-projects/AstrumPush-Smart-Recipe-Agent/protocol_tools.py","lineNumber":252,"sourceCode":"                \"\"\"友好问候\"\"\"\n                return f\"Hello, {name}! 欢迎使用 HelloAgents MCP 工具！\"\n\n            @server.tool()\n            def get_system_info() -> dict:\n                \"\"\"获取系统信息\"\"\"\n                import platform\n                import sys\n                return {\n                    \"platform\": platform.system(),\n                    \"python_version\": sys.version,\n                    \"server_name\": \"HelloAgents-BuiltinServer\",\n                    \"tools_count\": 6\n                }\n\n            return server\n\n        except ImportError:\n            raise ImportError(\n                \"创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp\"\n            )\n\n    def _discover_tools(self):\n        \"\"\"发现MCP服务器提供的所有工具\"\"\"\n        try:\n            from hello_agents.protocols.mcp.client import MCPClient\n            import asyncio\n\n            async def discover():\n                client_source = self.server if self.server else self.server_command\n                async with MCPClient(client_source, self.server_args, env=self.env) as client:\n                    tools = await client.list_tools()\n                    return tools\n\n            # 运行异步发现\n            try:\n                loop = asyncio.get_running_loop()","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/AstrumPush-Smart-Recipe-Agent/protocol_tools.py#L234-L270","documentation":"An ImportError raised by the built-in MCP server factory in protocol_tools.py when 'import fastmcp' (or the FastMCP symbol) fails. The code builds a demonstration MCP server with six tools (add through get_system_info) inside a try block; if the fastmcp distribution is absent or broken, the except ImportError re-raises with an install hint. This is a dependency-availability error, not a logic error.","triggerScenarios":"Instantiating the builtin MCP server component (which calls the factory returning 'server') in an environment where fastmcp is not installed, is installed under an incompatible Python version, or the package is corrupted so import raises ImportError. Installing via the suggested 'pip install fastmcp' into the active interpreter resolves it.","commonSituations":"Fresh environment where only hello_agents core was installed without the MCP extras; using a different virtualenv/conda env than the one where fastmcp was pip-installed; Python version mismatch yielding an unusable wheel; requirements.txt missing the optional dependency in deployment images.","solutions":["Run 'pip install fastmcp' in the same virtualenv/interpreter the agent runs under (verify with 'which python' / 'pip -V')","Pin it in requirements.txt or pyproject dependencies if the builtin server is used in deployment","If installation fails, check Python version compatibility with fastmcp's supported range","Alternatively pass server_command to use an external MCP server via stdio, avoiding the in-process fastmcp dependency"],"exampleFix":"# before\ntry:\n    from fastmcp import FastMCP\nexcept ImportError:\n    raise ImportError(\"创建内置 MCP 服务器需要 fastmcp 库。请安装: pip install fastmcp\")\n\n# after (shell)\n# pip install fastmcp\n# python -c \"import fastmcp; print(fastmcp.__version__)\"  # sanity check","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec('fastmcp') is None:\n    raise SystemExit('fastmcp missing — run: pip install fastmcp')\n# or in a shell: python -c \"import fastmcp\" || pip install fastmcp","typeGuard":"def fastmcp_available() -> bool:\n    import importlib.util\n    return importlib.util.find_spec('fastmcp') is not None","tryCatchPattern":"try:\n    server = build_builtin_server()\nexcept ImportError as e:\n    if 'fastmcp' in str(e):\n        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'fastmcp'])\n        server = build_builtin_server()  # retry once after install\n    else:\n        raise","preventionTips":["Declare fastmcp in project dependencies if you use the builtin MCP server","Install into the exact interpreter/virtualenv the agent runs under (pip -V to confirm)","Fall back to server_command (external MCP process via stdio) when the in-process dependency cannot be installed"],"tags":["mcp","fastmcp","dependency","import-error","installation"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}