# Demo MCP Server

这是一个用于学习目的的简单 MCP (Model Context Protocol) Server 演示项目。

## 什么是 MCP？

MCP (Model Context Protocol) 是一个开放协议，允许 AI 应用程序（如 Claude）与外部工具和数据源进行通信。通过 MCP，你可以：

- 为 Claude 提供自定义工具
- 集成外部 API 和服务
- 访问本地数据源
- 扩展 Claude 的能力

## 这个演示 Server 提供的工具

这个 demo MCP server 提供了三个简单的工具：

1. **calculate** - 执行基本算术运算（加、减、乘、除）
2. **get_current_time** - 获取当前日期和时间
3. **analyze_text** - 分析文本统计信息（字数、字符数等）

## 项目结构

```
.
├── demo_mcp_server.py    # MCP server 主程序
├── pyproject.toml         # Python 项目配置
├── claude_desktop_config.json  # Claude Desktop 配置示例
└── README.md              # 本文件
```

## 安装和运行

### 1. 安装依赖

使用 uv（推荐）：
```bash
uv pip install -e .
```

或使用 pip：
```bash
pip install -e .
```

### 2. 测试 Server

你可以直接运行 server 来测试它：
```bash
demo-mcp-server
```

或者使用 Python 运行：
```bash
python demo_mcp_server.py
```

### 3. 配置 Claude Code 使用此 MCP Server

要配置 Claude Code 使用这个 MCP server，你需要编辑 Claude Code 的配置文件。

**Claude Code 配置文件位置**：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

在配置文件中添加以下内容：

```json
{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/bytedance/workingspace/lzx-mcp",
        "run",
        "demo-mcp-server"
      ]
    }
  }
}
```

或者如果你使用的是系统 Python：
```json
{
  "mcpServers": {
    "demo-server": {
      "command": "demo-mcp-server"
    }
  }
}
```

**注意**：将 `/Users/bytedance/workingspace/lzx-mcp` 替换为你的实际项目路径。

### 4. 重启 Claude Code

配置完成后，重启 Claude Code 以加载新的 MCP server。

### 5. 使用 MCP 工具

重启后，你可以在 Claude Code 中这样使用：

```
请帮我计算 123 乘以 456

获取当前时间

分析这段文本的文字统计：Hello, this is a demo of the MCP server!
```

## MCP Server 工作原理

### 核心概念

1. **Server（服务器）**: 提供 tools 和资源的程序
2. **Client（客户端）**: 使用这些 tools 的应用程序（如 Claude）
3. **Tools（工具）**: 可以被 AI 调用的函数
4. **Transport（传输）**: Server 和 client 之间的通信方式（stdio, SSE 等）

### 代码结构解释

```python
# 1. 创建 Server 实例
app = Server("demo-mcp-server")

# 2. 列出可用工具
@app.list_tools()
async def list_tools() -> list[Tool]:
    # 返回所有可用工具的描述
    return [...]

# 3. 处理工具调用
@app.call_tool()
async def call_tool(name: str, arguments: dict):
    # 根据 tool name 路由到相应的处理函数
    ...

# 4. 运行 server
async def main():
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, ...)
```

## 扩展建议

想要添加更多工具？只需：

1. 在 `list_tools()` 中添加新的 Tool 定义
2. 在 `call_tool()` 中添加对应的处理函数
3. 实现具体的业务逻辑

示例：添加一个新的工具来获取天气信息
```python
Tool(
    name="get_weather",
    description="Get current weather for a city",
    inputSchema={
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "City name"},
        },
        "required": ["city"],
    },
)
```

## 参考资源

- [MCP 官方文档](https://modelcontextprotocol.io/)
- [MCP SDK Python](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Code 文档](https://claude.com/claude-code)

## License

MIT