docs/user-guides/MCP_SUPPORT.md

# Claude Agent MCP工具支持

Claude Agent通过Model Context Protocol (MCP)支持各种外部工具集成。

## 当前MCP架构

### 核心功能
- ✅ **动态MCP服务器加载**: 支持运行时加载MCP服务器
- ✅ **工具发现和注册**: 自动发现并注册MCP工具
- ✅ **工具调用管理**: 统一的工具调用接口
- ✅ **会话管理**: 管理MCP客户端会话生命周期

### 支持的MCP功能
- `call_tool` - 调用MCP工具
- `list_tools` - 列出可用工具
- `list_resources` - 列出可用资源
- `read_resource` - 读取资源内容
- `list_prompts` - 列出可用提示模板
- `get_prompt` - 获取提示模板
- `initialize` - 初始化MCP会话

## 可集成的MCP工具类型

### 1. 文件系统工具
```python
# 文件操作工具示例配置
await mcp_manager.load_mcp_server(
    "filesystem",
    "python",
    ["-m", "mcp_filesystem_server"]
)
```
**功能**: 文件读写、目录操作、文件搜索

### 2. 网络工具
```python
# HTTP请求工具示例
await mcp_manager.load_mcp_server(
    "http_tools",
    "python",
    ["-m", "mcp_http_server"]
)
```
**功能**: HTTP请求、API调用、网页抓取

### 3. 数据库工具
```python
# 数据库连接工具示例
await mcp_manager.load_mcp_server(
    "database",
    "python",
    ["-m", "mcp_database_server", "--db-url", "sqlite:///app.db"]
)
```
**功能**: SQL查询、数据库操作、数据分析

### 4. Git工具
```python
# Git操作工具示例
await mcp_manager.load_mcp_server(
    "git_tools",
    "python",
    ["-m", "mcp_git_server"]
)
```
**功能**: Git仓库操作、代码版本管理

### 5. 系统工具
```python
# 系统命令工具示例
await mcp_manager.load_mcp_server(
    "system",
    "python",
    ["-m", "mcp_system_server"]
)
```
**功能**: 系统命令执行、进程管理、环境变量

## 当前实现状态

### ✅ 已实现
- MCP客户端基础架构
- 工具加载和管理框架
- 工具调用接口
- 错误处理机制

### 🚧 需要配置
- 具体MCP服务器实例
- 工具权限管理
- 工具调用认证

## 使用示例

### 基础用法
```python
from claude_agent.mcp.integration import MCPToolManager

# 创建工具管理器
mcp_manager = MCPToolManager()

# 加载文件系统工具
await mcp_manager.load_mcp_server(
    "filesystem",
    "mcp-server-filesystem"
)

# 列出可用工具
tools = mcp_manager.get_available_tools()
print("可用工具:", tools)

# 调用工具
result = await mcp_manager.call_tool(
    "filesystem.read_file",
    {"path": "/path/to/file.txt"}
)
```

### 在Agent中使用
```python
# Agent会自动集成MCP工具
agent = AgentCore()

# 用户可以通过自然语言请求使用工具
response = await agent.process_user_input(
    "请帮我读取config.json文件的内容"
)
```

## 扩展MCP工具

### 添加新的MCP服务器
1. 实现MCP服务器协议
2. 在`setup_default_tools`中配置加载
3. 更新Agent的工具调用逻辑

### 自定义MCP工具
```python
# 在MCPToolIntegration.setup_default_tools()中添加
await self.tool_manager.load_mcp_server(
    "custom_tool",
    "python",
    ["-m", "my_custom_mcp_server"]
)
```

## 常见MCP工具服务器

| 工具类型 | 服务器包 | 功能描述 |
|---------|---------|---------|
| 文件系统 | `mcp-server-filesystem` | 文件读写、目录操作 |
| Git | `mcp-server-git` | Git仓库管理 |
| SQLite | `mcp-server-sqlite` | SQLite数据库操作 |
| HTTP | `mcp-server-fetch` | HTTP请求和API调用 |
| Shell | `mcp-server-shell` | Shell命令执行 |
| 时间 | `mcp-server-time` | 时间和日期处理 |

## 配置MCP工具

### 1. 安装MCP服务器
```bash
# 安装文件系统工具
pip install mcp-server-filesystem

# 安装Git工具
pip install mcp-server-git
```

### 2. 配置加载
在`claude_agent/mcp/integration.py`的`setup_default_tools`方法中添加：

```python
async def setup_default_tools(self):
    # 加载文件系统工具
    await self.tool_manager.load_mcp_server(
        "filesystem",
        "mcp-server-filesystem"
    )

    # 加载Git工具
    await self.tool_manager.load_mcp_server(
        "git",
        "mcp-server-git"
    )
```

## 注意事项

⚠️ **安全性**: MCP工具具有系统访问权限，使用时需要注意安全
⚠️ **权限管理**: 建议实现工具调用权限控制
⚠️ **错误处理**: 确保工具调用失败时有适当的降级机制

## 未来扩展

- [ ] 工具权限管理系统
- [ ] 工具调用日志和审计
- [ ] 更多内置MCP工具服务器
- [ ] 工具调用结果缓存
- [ ] 并发工具调用支持