Model Context Protocol

https://model-context-protocol.mintlify.app
Admin
The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide...
Tokens:23,193
Snippets:210
Trust Score:6.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize Project Environment

Source: https://model-context-protocol.mintlify.app/quickstart/server

Commands to create the project directory, initialize npm, and install necessary dependencies.

```bash
# 创建一个新目录用于我们的项目
mkdir weather
cd weather

# 初始化一个新的 npm 项目
npm init -y

# 安装依赖项
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript

# 创建我们的文件
mkdir src
touch src/index.ts
```

```powershell
# 创建一个新目录用于我们的项目
md weather
cd weather

# 初始化一个新的 npm 项目
npm init -y

# 安装依赖项
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript

# 创建我们的文件
md src
new-item src\index.ts
```

--------------------------------

### Verify Node.js Installation

Source: https://model-context-protocol.mintlify.app/quickstart/server

Check the installed versions of Node.js and npm to ensure compatibility.

```bash
node --version
npm --version
```

--------------------------------

### TypeScript 传输错误处理示例

Source: https://model-context-protocol.mintlify.app/docs/concepts/transports

在 start 和 send 方法中通过 try-catch 捕获异常，并调用 onerror 回调通知错误。

```typescript
class ExampleTransport implements Transport {
  async start() {
    try {
      // 连接逻辑
    } catch (error) {
      this.onerror?.(new Error(`连接失败：${error}`));
      throw error;
    }
  }

  async send(message: JSONRPCMessage) {
    try {
      // 发送逻辑
    } catch (error) {
      this.onerror?.(new Error(`发送消息失败：${error}`));
      throw error;
    }
  }
}
```

--------------------------------

### 定义包入口点 __init__.py

Source: https://model-context-protocol.mintlify.app/quickstart/server

在包级别定义主入口点以运行异步服务器逻辑。

```python
from . import server
import asyncio

def main():
    """包的主入口点。"""
    asyncio.run(server.main())

# 可选地在包级别公开其他重要项目
__all__ = ['main', 'server']
```

--------------------------------

### Run MCP Server Main Function

Source: https://model-context-protocol.mintlify.app/quickstart/server

Initializes the server using stdio streams and defines capabilities. Use asyncio.run to execute the main loop.

```python
async def main():
    # 使用 stdin/stdout 流运行服务器
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="weather",
                server_version="0.1.0",
                capabilities=server.get_capabilities(
                    notification_options=NotificationOptions(),
                    experimental_capabilities={},
                ),
            ),
        )

# 如果您想连接到自定义客户端，这是必需的
if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Initialize Server Instance

Source: https://model-context-protocol.mintlify.app/quickstart/server

Define API constants, Zod schemas, and initialize the MCP server instance.

```typescript
const NWS_API_BASE = "https://api.weather.gov";
const USER_AGENT = "weather-app/1.0";

// 定义 Zod 验证模式
const AlertsArgumentsSchema = z.object({
  state: z.string().length(2),
});

const ForecastArgumentsSchema = z.object({
  latitude: z.number().min(-90).max(90),
  longitude: z.number().min(-180).max(180),
});

// 创建服务器实例
const server = new Server(
  {
    name: "weather",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);
```

--------------------------------

### 检查 NPM 或 PyPi 服务器包

Source: https://model-context-protocol.mintlify.app/docs/tools/inspector

使用检查器启动远程托管的 MCP 服务器包。

```bash
npx -y @modelcontextprotocol/inspector npx <package-name> <args>
# 例如
npx -y @modelcontextprotocol/inspector npx server-postgres postgres://127.0.0.1/testdb
```

```bash
npx @modelcontextprotocol/inspector uvx <package-name> <args>
# 例如
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git
```

--------------------------------

### 配置 API 密钥

Source: https://model-context-protocol.mintlify.app/quickstart/client

创建 .env 文件并将其添加到 .gitignore 以安全存储 Anthropic API 密钥。

```bash
# 创建 .env 文件
touch .env
```

```bash
ANTHROPIC_API_KEY=<your key here>
```

```bash
echo ".env" >> .gitignore
```

--------------------------------

### 实现 Python 自定义传输接口

Source: https://model-context-protocol.mintlify.app/docs/concepts/transports

建议使用 anyio 实现低级传输接口，以确保与 asyncio 环境的广泛兼容性。

```python
@contextmanager
async def create_transport(
    read_stream: MemoryObjectReceiveStream[JSONRPCMessage | Exception],
    write_stream: MemoryObjectSendStream[JSONRPCMessage]
):
    """
    MCP 的传输接口。

    参数：
        read_stream：读取传入消息的流
        write_stream：写入传出消息的流
    """
    async with anyio.create_task_group() as tg:
        try:
            // 开始处理消息
            tg.start_soon(lambda: process_messages(read_stream))

            // 发送消息
            async with write_stream:
                yield write_stream

        except Exception as exc:
            // 处理错误
            raise exc
        finally:
            // 清理
            tg.cancel_scope.cancel()
            await write_stream.aclose()
            await read_stream.aclose()
```

--------------------------------

### 设置 Python 开发环境

Source: https://model-context-protocol.mintlify.app/quickstart/client

使用 uv 初始化项目、创建虚拟环境并安装必要的依赖包。

```bash
# 创建项目目录
uv init mcp-client
cd mcp-client

# 创建虚拟环境
uv venv

# 激活虚拟环境
# 在 Windows 上：
.venv\Scripts\activate
# 在 Unix 或 MacOS 上：
source .venv/bin/activate

# 安装所需的包
uv add mcp anthropic python-dotenv

# 删除样板文件
rm hello.py

# 创建我们的主文件
touch client.py
```

--------------------------------

### 运行 Python 参考服务器

Source: https://model-context-protocol.mintlify.app/examples

使用 uvx 或 pip 安装并运行基于 Python 的 MCP 服务器。

```bash
# 使用 uvx
uvx mcp-server-git

# 使用 pip
pip install mcp-server-git
python -m mcp_server_git
```

--------------------------------

### 实时跟踪 Claude 桌面日志

Source: https://model-context-protocol.mintlify.app/docs/tools/debugging

使用 tail 命令实时监控 macOS 上的 Claude 桌面 MCP 日志文件。

```bash
# 实时跟踪日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```

--------------------------------

### 处理 prompts/get 请求的资源嵌入

Source: https://model-context-protocol.mintlify.app/docs/concepts/prompts

在 prompts/get 请求中通过消息数组嵌入系统日志和代码文件资源。

```json
{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "分析这些系统日志和代码文件是否有任何问题："
      }
    },
    {
      "role": "user",
      "content": {
        "type": "resource",
        "resource": {
          "uri": "logs://recent?timeframe=1h",
          "text": "[2024-03-14 15:32:11] 错误：network.py:127 中的连接超时\n[2024-03-14 15:32:15] 警告：重试连接（尝试 2/3）\n[2024-03-14 15:32:20] 错误：超出最大重试次数",
          "mimeType": "text/plain"
        }
      }
    },
    {
      "role": "user",
      "content": {
        "type": "resource",
        "resource": {
          "uri": "file:///path/to/code.py",
          "text": "def connect_to_service(timeout=30):\n    retries = 3\n    for attempt in range(retries):\n        try:\n            return establish_connection(timeout)\n        except TimeoutError:\n            if attempt == retries - 1:\n                raise\n            time.sleep(5)\n\ndef establish_connection(timeout):\n    # 连接实现\n    pass",
          "mimeType": "text/x-python"
        }
      }
    }
  ]
}
```

--------------------------------

### Configure MCP Server in Claude Desktop

Source: https://model-context-protocol.mintlify.app/quickstart/server

JSON structure for registering the weather server in the Claude Desktop configuration file. Ensure absolute paths are used for the directory.

```json
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
                "run",
                "weather"
            ]
        }
    }
}
```

```json
{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather",
                "run",
                "weather"
            ]
        }
    }
}
```

--------------------------------

### 验证 Node.js 安装

Source: https://model-context-protocol.mintlify.app/quickstart/user

在命令行中检查 Node.js 是否已正确安装，这是运行 MCP 服务器的前提条件。

```bash
node --version
```

--------------------------------

### Python 传输错误处理示例

Source: https://model-context-protocol.mintlify.app/docs/concepts/transports

建议使用 anyio 实现低级传输接口，并在上下文管理器中处理初始化、消息处理及资源清理过程中的异常。

```python
@contextmanager
async def example_transport(scope: Scope, receive: Receive, send: Send):
    try:
        // 创建双向通信的流
        read_stream_writer, read_stream = anyio.create_memory_object_stream(0)
        write_stream, write_stream_reader = anyio.create_memory_object_stream(0)

        async def message_handler():
            try:
                async with read_stream_writer:
                    // 消息处理逻辑
                    pass
            except Exception as exc:
                logger.error(f"处理消息失败：{exc}")
                raise exc

        async with anyio.create_task_group() as tg:
            tg.start_soon(message_handler)
            try:
                // 提供通信流
                yield read_stream, write_stream
            except Exception as exc:
                logger.error(f"传输错误：{exc}")
                raise exc
            finally:
                tg.cancel_scope.cancel()
                await write_stream.aclose()
                await read_stream.aclose()
    except Exception as exc:
        logger.error(f"初始化传输失败：{exc}")
        raise exc
```

--------------------------------

### 初始化 Python 项目结构

Source: https://model-context-protocol.mintlify.app/quickstart/server

创建项目目录、虚拟环境并安装必要的 MCP 依赖项。

```bash
# 创建一个新目录用于我们的项目
uv init weather
cd weather

# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate

# 安装依赖项
uv add mcp httpx 

# 删除模板文件
rm hello.py

# 创建我们的文件
mkdir -p src/weather
touch src/weather/__init__.py
touch src/weather/server.py
```

```powershell
# 创建一个新目录用于我们的项目
uv init weather
cd weather

# 创建虚拟环境并激活它
uv venv
.venv\Scripts\activate

# 安装依赖项
uv add mcp httpx

# 清理样板代码
rm hello.py

# 创建我们的文件
md src
md src\weather
new-item src\weather\__init__.py
new-item src\weather\server.py
```

--------------------------------

### 实现服务器连接管理

Source: https://model-context-protocol.mintlify.app/quickstart/client

通过 stdio 传输连接到指定的 MCP 服务器脚本并初始化会话。

```python
async def connect_to_server(self, server_script_path: str):
    """连接到 MCP 服务器
    
    参数:
        server_script_path: 服务器脚本的路径 (.py 或 .js)
    """
    is_python = server_script_path.endswith('.py')
    is_js = server_script_path.endswith('.js')
    if not (is_python or is_js):
        raise ValueError("服务器脚本必须是 .py 或 .js 文件")
        
    command = "python" if is_python else "node"
    server_params = StdioServerParameters(
        command=command,
        args=[server_script_path],
        env=None
    )
    
    stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
    self.stdio, self.write = stdio_transport
    self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
    
    await self.session.initialize()
    
    # 列出可用工具
    response = await self.session.list_tools()
    tools = response.tools
    print("\n已连接到具有工具的服务器:", [tool.name for tool in tools])
```

--------------------------------

### 运行 MCP 客户端

Source: https://model-context-protocol.mintlify.app/quickstart/client

使用 uv 运行不同类型的服务器脚本。

```bash
uv run client.py path/to/server.py # python 服务器
uv run client.py path/to/build/index.js # node 服务器
```

--------------------------------

### 配置 pyproject.toml 脚本入口

Source: https://model-context-protocol.mintlify.app/quickstart/server

在 pyproject.toml 中定义项目脚本入口点以运行服务器。

```toml
...rest of config

[build-system]
requires = [ "hatchling",]
build-backend = "hatchling.build"

[project.scripts]
weather = "weather:main"
```

--------------------------------

### Open Claude Desktop Configuration

Source: https://model-context-protocol.mintlify.app/quickstart/server

Commands to open the configuration file for Claude for Desktop on different operating systems.

```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

```powershell
code $env:AppData\Claude\claude_desktop_config.json
```

--------------------------------

### 配置 MCP 服务器环境变量

Source: https://model-context-protocol.mintlify.app/docs/tools/debugging

在 claude_desktop_config.json 中通过 env 键为服务器指定自定义环境变量。

```json
{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}
```

--------------------------------

### 配置 MCP 服务器

Source: https://model-context-protocol.mintlify.app/quickstart/server

在 claude_desktop_config.json 中添加服务器定义，指定启动命令和路径。

```json
{
    "mcpServers": {
        "weather": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
            ]
        }
    }
}
```

```json
{
    "mcpServers": {
        "weather": {
            "command": "node",
            "args": [
                "C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js"
            ]
        }
    }
}
```

--------------------------------

### 导入 MCP 服务器依赖

Source: https://model-context-protocol.mintlify.app/quickstart/server

在 server.py 中导入必要的 MCP 和异步 HTTP 库。

```python
from typing import Any
import asyncio
import httpx
from mcp.server.models import InitializationOptions
import mcp.types as types
from mcp.server import NotificationOptions, Server
import mcp.server.stdio
```

--------------------------------

### 服务器路径配置示例

Source: https://model-context-protocol.mintlify.app/quickstart/client

展示如何使用相对路径、绝对路径以及 Windows 格式路径运行客户端。

```bash
# 相对路径
uv run client.py ./server/weather.py

# 绝对路径
uv run client.py /Users/username/projects/mcp-server/weather.py

# Windows 路径（任一格式均可）
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py
```

--------------------------------

### 启用 Claude 桌面开发者工具

Source: https://model-context-protocol.mintlify.app/docs/tools/debugging

通过修改 developer_settings.json 文件启用 Claude 桌面版的 Chrome DevTools。

```bash
jq '.allowDevTools = true' ~/Library/Application\ Support/Claude/developer_settings.json > tmp.json \
  && mv tmp.json ~/Library/Application\ Support/Claude/developer_settings.json
```

--------------------------------

### 运行 TypeScript 参考服务器

Source: https://model-context-protocol.mintlify.app/examples

使用 npx 直接运行基于 TypeScript 的 MCP 服务器。

```bash
npx -y @modelcontextprotocol/server-memory
```

--------------------------------

### 运行 MCP 检查器基础命令

Source: https://model-context-protocol.mintlify.app/docs/tools/inspector

通过 npx 直接运行检查器，无需预先安装。

```bash
npx @modelcontextprotocol/inspector <command>
```

```bash
npx @modelcontextprotocol/inspector <command> <arg1> <arg2>
```

--------------------------------

### 安装 uv 环境管理工具

Source: https://model-context-protocol.mintlify.app/quickstart/server

根据操作系统安装 uv 以管理 Python 项目依赖。

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### 配置 MCP 服务器绝对路径

Source: https://model-context-protocol.mintlify.app/docs/tools/debugging

在 claude_desktop_config.json 中使用绝对路径以确保服务器在不同启动环境下正常工作。

```json
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
```

--------------------------------

### prompts/list

Source: https://model-context-protocol.mintlify.app/docs/concepts/prompts

Retrieves a list of all available prompt templates defined by the server.

```APIDOC
## prompts/list

### Description
Fetches the list of available prompts that the server exposes to the client.

### Request
{
  "method": "prompts/list"
}

### Response
- **prompts** (array) - A list of prompt objects containing name, description, and arguments.
```

--------------------------------

### resources/list

Source: https://model-context-protocol.mintlify.app/docs/concepts/resources

Retrieves a list of available resources from the server.

```APIDOC
## resources/list

### Description
Returns a list of resources available on the server. Each resource includes a URI, a human-readable name, and optional metadata like description and MIME type.

### Response
- **resources** (array) - List of available resources
  - **uri** (string) - The unique identifier for the resource
  - **name** (string) - Human-readable name
  - **description** (string, optional) - Description of the resource
  - **mimeType** (string, optional) - MIME type of the resource
```

--------------------------------

### prompts/get

Source: https://model-context-protocol.mintlify.app/docs/concepts/prompts

Retrieves the content of a specific prompt template by its name, including any required arguments.

```APIDOC
## prompts/get

### Description
Retrieves a specific prompt template and its associated messages based on the provided name and arguments.

### Request
{
  "method": "prompts/get",
  "params": {
    "name": "string",
    "arguments": "object"
  }
}

### Response
- **description** (string) - Human-readable description of the prompt.
- **messages** (array) - The list of messages associated with the prompt execution.
```

--------------------------------

### Implement Tool List Handler

Source: https://model-context-protocol.mintlify.app/quickstart/server

Register available tools with the server using a request handler.

```typescript
// 列出可用工具
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get-alerts",
        description: "获取某个州的天气警报",
        inputSchema: {
          type: "object",
          properties: {
            state: {
              type: "string",
              description: "两字母州代码（例如 CA，NY）",
            },
          },
          required: ["state"],
        },
      },
      {
        name: "get-forecast",
        description: "获取某个位置的天气预报",
        inputSchema: {
          type: "object",
          properties: {
            latitude: {
              type: "number",
              description: "位置的纬度",
            },
            longitude: {
              type: "number",
              description: "位置的经度",
            },
          },
          required: ["latitude", "longitude"],
        },
      },
    ],
  };
});
```

--------------------------------

### Configure package.json

Source: https://model-context-protocol.mintlify.app/quickstart/server

Update package.json to support ES modules and define build scripts.

```json
{
  "type": "module",
  "bin": {
    "weather": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
  },
  "files": [
    "build"
  ],
}
```

--------------------------------

### Implement Helper Functions

Source: https://model-context-protocol.mintlify.app/quickstart/server

Provides utility functions for making HTTP requests to the NWS API and formatting the resulting data.

```python
async def make_nws_request(client: httpx.AsyncClient, url: str) -> dict[str, Any] | None:
    """
    向 NWS API 发出请求并进行适当的错误处理。
    """
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }

    try:
        response = await client.get(url, headers=headers, timeout=30.0)
        response.raise_for_status()
        return response.json()
    except Exception:
        return None

def format_alert(feature: dict) -> str:
    """
    将警报功能格式化为简洁的字符串。
    """
    props = feature["properties"]
    return (
        f"事件: {props.get('event', '未知')}\n"
        f"区域: {props.get('areaDesc', '未知')}\n"
        f"严重性: {props.get('severity', '未知')}\n"
        f"状态: {props.get('status', '未知')}\n"
        f"标题: {props.get('headline', '无标题')}\n"
        "---"
    )
```

--------------------------------

### 发送服务器日志消息

Source: https://model-context-protocol.mintlify.app/docs/tools/debugging

通过协议向客户端发送日志消息，适用于各种传输方式。

```python
server.request_context.session.send_log_message(
  level="info",
  data="Server started successfully",
)
```

```typescript
server.sendLoggingMessage({
  level: "info",
  data: "Server started successfully",
});
```

--------------------------------

### 实现服务器主函数

Source: https://model-context-protocol.mintlify.app/quickstart/server

使用 StdioServerTransport 启动服务器。确保在运行前执行 npm run build。

```typescript
// 启动服务器
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP 服务器在 stdio 上运行");
}

main().catch((error) => {
  console.error("main() 中的致命错误：", error);
  process.exit(1);
});
```

--------------------------------

### 初始化 MCP 客户端类

Source: https://model-context-protocol.mintlify.app/quickstart/client

设置必要的导入并定义 MCPClient 类以管理会话和 Anthropic 客户端。

```python
import asyncio
from typing import Optional
from contextlib import AsyncExitStack

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv()  # 从 .env 加载环境变量

class MCPClient:
    def __init__(self):
        # 初始化会话和客户端对象
        self.session: Optional[ClientSession] = None
        self.exit_stack = AsyncExitStack()
        self.anthropic = Anthropic()
    # 方法将在这里添加
```

--------------------------------

### 初始化服务器实例

Source: https://model-context-protocol.mintlify.app/quickstart/server

设置服务器名称和 API 基础 URL。

```python
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

server = Server("weather")
```

--------------------------------

### 处理查询与工具调用

Source: https://model-context-protocol.mintlify.app/quickstart/client

实现将用户查询发送给 Claude 并根据响应执行 MCP 工具调用的逻辑。

```python
async def process_query(self, query: str) -> str:
    """使用 Claude 和可用工具处理查询"""
    messages = [
        {
            "role": "user",
            "content": query
        }
    ]

    response = await self.session.list_tools()
    available_tools = [{ 
        "name": tool.name,
        "description": tool.description,
        "input_schema": tool.inputSchema
    } for tool in response.tools]

    # 初始 Claude API 调用
    response = self.anthropic.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1000,
        messages=messages,
        tools=available_tools
    )

    # 处理响应并处理工具调用
    tool_results = []
    final_text = []

    for content in response.content:
        if content.type == 'text':
            final_text.append(content.text)
        elif content.type == 'tool_use':
            tool_name = content.name
            tool_args = content.input
            
            # 执行工具调用
            result = await self.session.call_tool(tool_name, tool_args)
            tool_results.append({"call": tool_name, "result": result})
            final_text.append(f"[调用工具 {tool_name}，参数 {tool_args}]")

            # 使用工具结果继续对话
            if hasattr(content, 'text') and content.text:
                messages.append({
                  "role": "assistant",
                  "content": content.text
                })
            messages.append({
                "role": "user", 
                "content": result.content
            })
```

--------------------------------

### 检查本地开发的服务器

Source: https://model-context-protocol.mintlify.app/docs/tools/inspector

针对本地 TypeScript 或 Python 项目启动检查器进行调试。

```bash
npx @modelcontextprotocol/inspector node path/to/server/index.js args...
```

```bash
npx @modelcontextprotocol/inspector \
  uv \
  --directory path/to/server \
  run \
  package-name \
  args...
```

--------------------------------

### Configure tsconfig.json

Source: https://model-context-protocol.mintlify.app/quickstart/server

Set up TypeScript compiler options for the project.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
```

--------------------------------

### 实现多步骤调试工作流程

Source: https://model-context-protocol.mintlify.app/docs/concepts/prompts

使用 TypeScript 定义一个异步函数，通过预定义的消息序列引导用户进行错误分析。

```typescript
const debugWorkflow = {
  name: "debug-error",
  async getMessages(error: string) {
    return [
      {
        role: "user",
        content: {
          type: "text",
          text: `这是我看到的一个错误：${error}`
        }
      },
      {
        role: "assistant",
        content: {
          type: "text",
          text: "我会帮助分析这个错误。你已经尝试了什么？"
        }
      },
      {
        role: "user",
        content: {
          type: "text",
          text: "我已经尝试重新启动服务，但错误仍然存在。"
        }
      }
    ];
  }
};
```

--------------------------------

### 实现 MCP 服务器

Source: https://model-context-protocol.mintlify.app/docs/concepts/architecture

展示了使用 SDK 创建 MCP 服务器并处理资源列表请求的基本模式。

```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "example-server",
  version: "1.0.0"
}, {
  capabilities: {
    resources: {}
  }
});

// 处理请求
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: "example://resource",
        name: "Example Resource"
      }
    ]
  };
});

// 连接传输
const transport = new StdioServerTransport();
await server.connect(transport);
```

```python
import asyncio
import mcp.types as types
from mcp.server import Server
from mcp.server.stdio import stdio_server

app = Server("example-server")

@app.list_resources()
async def list_resources() -> list[types.Resource]:
    return [
        types.Resource(
            uri="example://resource",
            name="Example Resource"
        )
    ]

async def main():
    async with stdio_server() as streams:
        await app.run(
            streams[0],
            streams[1],
            app.create_initialization_options()
        )

if __name__ == "__main__":
    asyncio.run(main)
```

--------------------------------

### 查看 Claude 桌面版日志

Source: https://model-context-protocol.mintlify.app/quickstart/user

使用命令行工具查看 MCP 连接日志和服务器错误输出，有助于诊断连接失败或工具调用静默失败的问题。

```bash
# 检查 Claude 的日志以查找错误
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
```

```bash
type "%APPDATA%\Claude\logs\mcp*.log"
```

--------------------------------

### 发现可用提示

Source: https://model-context-protocol.mintlify.app/docs/concepts/prompts

通过 prompts/list 端点获取服务器提供的提示列表。

```typescript
// 请求
{
  method: "prompts/list"
}

// 响应
{
  prompts: [
    {
      name: "analyze-code",
      description: "分析代码以寻找潜在的改进",
      arguments: [
        {
          name: "language",
          description: "编程语言",
          required: true
        }
      ]
    }
  ]
}
```

--------------------------------

### 定义系统操作工具

Source: https://model-context-protocol.mintlify.app/docs/concepts/tools

定义一个用于执行 shell 命令的工具，包含命令字符串和参数数组。

```typescript
{
  name: "execute_command",
  description: "运行 shell 命令",
  inputSchema: {
    type: "object",
    properties: {
      command: { type: "string" },
      args: { type: "array", items: { type: "string" } }
    }
  }
}
```

--------------------------------

### 手动运行 MCP 服务器进行调试

Source: https://model-context-protocol.mintlify.app/quickstart/user

通过命令行手动启动服务器以检查配置错误或路径问题，需将路径替换为实际的绝对路径。

```bash
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads`
```

```bash
npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
```

--------------------------------

### 获取并使用提示

Source: https://model-context-protocol.mintlify.app/docs/concepts/prompts

通过 prompts/get 端点请求特定提示，并传入必要的参数以获取预定义的交互消息。

```typescript
// 请求
{
  method: "prompts/get",
  params: {
    name: "analyze-code",
    arguments: {
      language: "python"
    }
  }
}

// 响应
{
  description: "分析 Python 代码以寻找潜在的改进",
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: "请分析以下 Python 代码以寻找潜在的改进：\n\n```python\ndef calculate_sum(numbers):\n    total = 0\n    for num in numbers:\n        total = total + num\n    return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n```"
      }
    }
  ]
}
```

--------------------------------

### 定义 API 集成工具

Source: https://model-context-protocol.mintlify.app/docs/concepts/tools

定义一个用于创建 GitHub Issue 的工具，要求提供标题、正文和标签。

```typescript
{
  name: "github_create_issue",
  description: "创建 GitHub 问题",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      body: { type: "string" },
      labels: { type: "array", items: { type: "string" } }
    }
  }
}
```

--------------------------------

### Import MCP Packages

Source: https://model-context-protocol.mintlify.app/quickstart/server

Required imports for the MCP server implementation.

```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";
```

--------------------------------

### 获取 Claude 响应片段

Source: https://model-context-protocol.mintlify.app/quickstart/client

用于向 Claude 发送消息并获取响应的逻辑片段。

```python
                response = self.anthropic.messages.create(
                    model="claude-3-5-sonnet-20241022",
                    max_tokens=1000,
                    messages=messages,
                )

                final_text.append(response.content[0].text)

        return "\n".join(final_text)
```

--------------------------------

### 实现 MCP 提示服务器

Source: https://model-context-protocol.mintlify.app/docs/concepts/prompts

展示了如何使用 TypeScript 和 Python SDK 定义提示列表并处理获取提示的请求。

```typescript
import { Server } from "@modelcontextprotocol/sdk/server";
import {
  ListPromptsRequestSchema,
  GetPromptRequestSchema
} from "@modelcontextprotocol/sdk/types";

const PROMPTS = {
  "git-commit": {
    name: "git-commit",
    description: "生成 Git 提交消息",
    arguments: [
      {
        name: "changes",
        description: "Git diff 或更改描述",
        required: true
      }
    ]
  },
  "explain-code": {
    name: "explain-code",
    description: "解释代码如何工作",
    arguments: [
      {
        name: "code",
        description: "要解释的代码",
        required: true
      },
      {
        name: "language",
        description: "编程语言",
        required: false
      }
    ]
  }
};

const server = new Server({
  name: "example-prompts-server",
  version: "1.0.0"
}, {
  capabilities: {
    prompts: {}
  }
});

// 列出可用提示
server.setRequestHandler(ListPromptsRequestSchema, async () => {
  return {
    prompts: Object.values(PROMPTS)
  };
});

// 获取特定提示
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
  const prompt = PROMPTS[request.params.name];
  if (!prompt) {
    throw new Error(`未找到提示：${request.params.name}`);
  }

  if (request.params.name === "git-commit") {
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `为这些更改生成简洁但描述性的提交消息：\n\n${request.params.arguments?.changes}`
          }
        }
      ]
    };
  }

  if (request.params.name === "explain-code") {
    const language = request.params.arguments?.language || "未知";
    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `解释这段 ${language} 代码如何工作：\n\n${request.params.arguments?.code}`
          }
        }
      ]
    };
  }

  throw new Error("未找到提示实现");
});
```

```python
from mcp.server import Server
import mcp.types as types

# 定义可用提示
PROMPTS = {
    "git-commit": types.Prompt(
        name="git-commit",
        description="生成 Git 提交消息",
        arguments=[
            types.PromptArgument(
                name="changes",
                description="Git diff 或更改描述",
                required=True
            )
        ],
    ),
    "explain-code": types.Prompt(
        name="explain-code",
        description="解释代码如何工作",
        arguments=[
            types.PromptArgument(
                name="code",
                description="要解释的代码",
                required=True
            ),
            types.PromptArgument(
                name="language",
                description="编程语言",
                required=False
            )
        ],
    )
}

# 初始化服务器
app = Server("example-prompts-server")

@app.list_prompts()
async def list_prompts() -> list[types.Prompt]:
    return list(PROMPTS.values())

@app.get_prompt()
async def get_prompt(
    name: str, arguments: dict[str, str] | None = None
) -> types.GetPromptResult:
    if name not in PROMPTS:
        raise ValueError(f"未找到提示：{name}")

    if name == "git-commit":
        changes = arguments.get("changes") if arguments else ""
        return types.GetPromptResult(
            messages=[
                types.PromptMessage(
                    role="user",
                    content=types.TextContent(
                        type="text",
                        text=f"为这些更改生成简洁但描述性的提交消息：\n\n{changes}"
                    )
                )
            ]
        )

    if name == "explain-code":
        code = arguments.get("code") if arguments else ""
        language = arguments.get("language", "未知") if arguments else "未知"
        return types.GetPromptResult(
            messages=[
                types.PromptMessage(
                    role="user",
                    content=types.TextContent(
                        type="text",
                        text=f"解释这段 {language} 代码如何工作：\n\n{code}"
                    )
                )
            ]
        )

    raise ValueError("未找到提示实现")
```

--------------------------------

### 配置 Claude MCP 服务器

Source: https://model-context-protocol.mintlify.app/examples

将 MCP 服务器添加到 Claude 的配置文件中以启用集成。

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}
```
Tokens:
Raw