# catmcp

**Repository Path**: edfeff/catmcp

## Basic Information

- **Project Name**: catmcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CatMCP - Model Context Protocol 实现

一个基于 Python 的 MCP (Model Context Protocol) 实现示例，展示了如何通过标准输入输出实现 MCP 客户端和服务器，并与大语言模型集成。

## 项目简介

CatMCP 实现了 MCP 协议的核心功能，包括：
- MCP 服务器：提供工具调用能力（天气查询、新闻搜索）
- MCP 客户端：通过标准输入输出与服务器通信
- LLM 集成：使用 OpenAI 兼容 API 与大语言模型交互

## 项目结构

```
catmcp/
├── main.py              # 主入口文件，演示如何使用 MCP 客户端
├── stdio_client.py      # MCP 客户端实现
├── stdio_server.py      # MCP 服务器实现
├── requirements.txt     # 项目依赖
├── .gitignore          # Git 忽略文件
└── README.md           # 项目说明文档
```

## 功能特性

### MCP 服务器 (stdio_server.py)
- 实现 JSON-RPC 2.0 协议
- 支持的工具：
  - `get_weather`: 获取指定地点的天气信息
  - `search_news`: 根据关键词搜索新闻
- 通过标准输入输出接收请求和发送响应

### MCP 客户端 (stdio_client.py)
- 通过子进程启动 MCP 服务器
- 实现 JSON-RPC 客户端
- 与 LLM 集成，支持工具调用和响应处理
- 支持多轮对话和工具调用

## 技术栈

- Python 3.12+
- OpenAI SDK (用于 LLM 交互)
- python-dotenv (环境变量管理)
- 阿里云 DashScope API (qwen-plus 模型)

## 安装依赖

```bash
pip install -r requirements.txt
```

## 环境配置

创建 `.env` 文件并配置 API 密钥：

```
API_KEY=your_api_key_here
```

## 使用方法

### 运行示例

```bash
python main.py
```

示例会执行两个任务：
1. 搜索今日新闻
2. 查询上海天气

### 自定义使用

```python
from stdio_client import run_agent_with_mcp

# 执行自定义任务
result = run_agent_with_mcp("你的任务描述")
print(result)
```

## MCP 协议实现

### 支持的方法

服务器支持以下 JSON-RPC 方法：

- `initialize`: 初始化服务器，返回协议版本和工具能力
- `tools/list`: 列出所有可用工具
- `tools/call`: 执行指定工具

### 工具定义

工具定义包含以下字段：
- `name`: 工具名称
- `description`: 工具描述
- `inputSchema`: 输入参数的 JSON Schema
- `handler`: 工具处理函数

## 示例输出

```
[MCP] search_news {'query': '今日新闻'}
搜索关键词：今日新闻，搜索结果:
国内油价24日将迎年内第六轮调整，预计每升上涨约1.6元‌，或将重回"9元时代"，加满一箱油或多花100元；
中办、国办发布关于做好第二轮土地承包到期后再延长30年试点工作的意见；

[MCP] get_weather {'location': '上海'}
上海的天气是晴，温度是22摄氏度
```

## 扩展开发

### 添加新工具

在 `stdio_server.py` 中的 `TOOLS` 字典添加新工具：

```python
def your_tool_function(param):
    # 实现工具逻辑
    return "result"

TOOLS["your_tool"] = {
    "description": "工具描述",
    "inputSchema": {
        "type": "object",
        "properties": {
            "param": {"type": "string", "description": "参数描述"}
        },
        "required": ["param"],
    },
    "handler": your_tool_function,
}
```

### 自定义 LLM

修改 `stdio_client.py` 中的 LLM 配置：

```python
llm = OpenAI(
    api_key=os.getenv("API_KEY"),
    base_url="your_base_url"
)
```

## 注意事项

- 确保已正确配置 `.env` 文件中的 API 密钥
- MCP 服务器通过标准输入输出通信，确保管道正常工作
- 当前实现使用模拟数据，实际应用中可替换为真实 API

## 许可证

本项目仅供学习和参考使用。