mcp-python

分类: 开发与编程 | 上传者: antoinebou12 | 下载: 0 | 版本: v1.0（最新）

使用 FastMCP 和官方 SDK 在 Python 中创建和扩展 MCP（模型上下文协议）服务器。涵盖工具、资源、提示、STDIO 与 HTTP 传输、STDIO 日志记录规则以及生产最佳实践。在 Python 中构建或修改 MCP 服务器、添加工具/资源/提示、调试 MCP 服务器或选择传输和客户端配置时使用。

更新日志: Source: GitHub https://github.com/antoinebou12/uml-mcp

目录结构

当前层级: tree/main/.skill/skills/mcp-python/

📄 SKILL.md 4.3 KB

SKILL.md

---
name: mcp-python
description: Create and extend MCP (Model Context Protocol) servers in Python using FastMCP and the official SDK. Covers tools, resources, prompts, STDIO vs HTTP transports, logging rules for STDIO, and production best practices. Use when building or modifying MCP servers in Python, adding tools/resources/prompts, debugging MCP servers, or choosing transport and client config.
---

# MCP Servers in Python

Create and extend MCP servers in Python with FastMCP and the official MCP Python SDK. Based on [MCP Build a server](https://modelcontextprotocol.io/docs/develop/build-server) and [MCP Best Practices](https://mcp-best-practice.github.io/mcp-best-practice/best-practice/).

## When to Use

- Building or extending MCP servers in Python
- Adding tools, resources, or prompts
- Debugging MCP server connection or tool discovery
- Choosing transport (stdio vs streamable HTTP)
- Configuring clients (Claude Desktop, Cursor) to run the server

## Core Concepts

- **Tools**: Functions callable by the LLM (with user approval). Have explicit input/output and side-effect disclosure.
- **Resources**: Readable data (files, API responses) the client fetches for context. URI-based.
- **Prompts**: Pre-written templates for specific tasks; reduce prompt drift.
- **Discovery**: Clients enumerate tools/resources/prompts and get schemas at connect time.
- **Transports**: **stdio** for local, per-user processes; **streamable HTTP** for remote, shared services.

## FastMCP Quick Reference

Python 3.12, MCP Python SDK 1.2.0+. Use `uv add "mcp[cli]"` or `uv add fastmcp` (or project may use `fastmcp` package).

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get weather forecast for a location.
    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # ... fetch and return string
    return result

@mcp.resource("config://{key}")
def get_config(key: str) -> str:
    """Get config value by key."""
    return config_store.get(key, "")

@mcp.prompt()
def plan_task(goal: str, steps: int = 5) -> str:
    """Generate a step-by-step plan. Args: goal, steps (default 5)."""
    return f"Plan for: {goal} in {steps} steps."

def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()
```

- **Tool schemas**: FastMCP infers names, types, and descriptions from type hints and docstrings (Args/Returns).
- **Run**: `mcp.run(transport="stdio")` for stdio; use streamable HTTP for remote deployment.

## STDIO Critical Rule

For **STDIO-based servers**, never write to **stdout**. JSON-RPC uses stdout; any print or stdout write corrupts messages and breaks the server.

- **Bad**: `print("Processing")`, `sys.stdout.write(...)`
- **Good**: `import logging` and `logging.info(...)` (logging writes to stderr by default), or log to a file.

For HTTP-based servers, stdout logging is fine.

## Best Practices (Short)

- **Single responsibility**: One clear domain and auth boundary per server.
- **Bounded toolsets**: Focused tools with specific contracts; avoid kitchen-sink servers.
- **Contracts first**: Strict input/output schemas, explicit side effects, documented errors.
- **Stateless by default**: No hidden in-memory state; use external stores if needed.
- **Least privilege**: Precise tools; gate high-impact or destructive actions behind approval.
- **Additive change**: Version tool schemas; prefer additive evolution; deprecate with notice.

## Scaffolding a New Server

```bash
uvx create-mcp-server
# Follow prompts; then:
cd <generated-project>
uv sync --dev --all-extras
uv run <server-module>
```

## Client Config (stdio)

Example for Claude Desktop or Cursor MCP (stdio, using uv):

```json
{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/project", "run", "server.py"]
    }
  }
}
```

Use absolute path to the project directory. On Windows use forward slashes or escaped backslashes in JSON.

## References

- [Build an MCP server (Python)](https://modelcontextprotocol.io/docs/develop/build-server)
- [MCP Best Practices](https://mcp-best-practice.github.io/mcp-best-practice/best-practice/)
- [MCP Python SDK](https://modelcontextprotocol.github.io/python-sdk/)

登录后下载/点赞/收藏 ❤ 83 | ★ 0

mcp-python

目录结构

SKILL.md

举报内容

提示