abroad-mcp-server-qiangyang 1.0.4
一个规范、可扩展的MCP（Model Capability Protocol）工具开发框架
Requires Python: >=3.10

# MCP开发框架

一个规范、可扩展的MCP（Model Capability Protocol）工具开发框架，用于创建可被Claude、Cursor等AI助手直接调用的工具。

## 特点

- **模块化设计**: 易于扩展和维护
- **多人协作支持**: 规范化的结构，适合团队开发
- **内置工具示例**: 包含天气、翻译等实用工具示例
- **完整错误处理**: 全面的异常捕获和日志记录
- **灵活配置管理**: 支持配置文件和环境变量
- **详细文档**: 包含完整的入门教程和开发指南

## 目录结构

```
mcp_framework/
├── __init__.py         # 包初始化文件
├── __main__.py         # 支持直接运行的入口
├── mcp_server.py       # 主服务器实现
├── config/             # 配置模块
│   ├── settings.py     # 配置管理
│   ├── sample_config.json  # 示例配置
│   └── cursor_mcp.json # Cursor配置示例
├── mcp_tools/          # MCP工具集合
│   ├── __init__.py     # 初始化FastMCP实例
│   ├── weather.py      # 天气相关工具
│   └── translate.py    # 翻译相关工具
├── utils/              # 工具函数
│   ├── http.py         # HTTP请求工具
│   └── logger.py       # 日志工具
└── docs/               # 文档
    ├── README.md       # 本文档
    └── tutorial.md     # 详细教程
```

## 快速开始

### 安装依赖

```bash
pip install uv mcp httpx loguru
```

### 运行服务器

使用Python直接运行（开发环境）:
```bash
python -m mcp_framework
```

使用uv工具运行（推荐生产环境）:
```bash
nohup uv --directory /path/to/project run python -m mcp_framework --transport sse >/dev/null 2>&1 &

```

### 配置Cursor

编辑 `~/.cursor/mcp.json`，添加服务器配置：

```json
{
  "mcpServers": {
    "mytools": {
      "command": "uv",
      "args": ["--directory", "/path/to/your/project", "run", "python", "-m", "mcp_framework"],
      "env": {
        "PYTHONPATH": "/path/to/your/python/site-packages"
      }
    }
  }
}
```

### 创建自定义工具

在`mcp_tools`目录下创建新的Python文件，按照指定格式添加工具函数：

```python
from typing import Dict, Any
from loguru import logger
from mcp_framework.mcp_tools import mcp

@mcp.tool()
async def hello(name: str) -> str:
    """一个简单的问候工具
    
    Args:
        name: 要问候的人名
        
    Returns:
        问候消息
    """
    logger.info(f"问候: {name}")
    return f"你好，{name}！欢迎使用MCP工具！"
```

## 文档

- [入门教程](tutorial.md) - 详细的开发指南
- [API参考文档]() - 待添加
- [MCP协议文档](https://mcp-docs.cn/) - 官方MCP文档

## 贡献

欢迎提交问题报告、功能请求或Pull Request。

## 部署与集成

### Cursor集成

要在Cursor中使用此框架开发的MCP工具：

1. **安装依赖**：确保已安装所需Python包
   ```bash
   pip install mcp httpx loguru
   ```

2. **配置Cursor**：编辑 `~/.cursor/mcp.json` 文件
   ```json
   {
     "mcpServers": {
       "mytools": {
         "command": "uv",
         "args": ["--directory", "/path/to/your/project", "run", "python", "-m", "mcp_framework"],
         "env": {
           "PYTHONPATH": "/path/to/your/python/site-packages"
         }
       }
     }
   }
   ```

3. **重启Cursor**：完成配置后重启Cursor以加载新的MCP工具
   
4. **使用工具**：在Cursor中，您可以直接调用定义的工具，如：
   ```
   我想查询北京的天气
   ```

### Dify集成

要将此MCP框架集成到Dify平台：

1. **启动HTTP服务器**：使用HTTP模式启动服务
   ```bash
   # 设置环境变量
   export MCP_TRANSPORT=http
   export MCP_HTTP_HOST=0.0.0.0
   export MCP_HTTP_PORT=5678
   
   # 启动服务
   uv --directory /path/to/project run python -m mcp_framework
   ```

2. **公开HTTP端点**：如果服务在内网，需要设置反向代理或使用内网穿透工具
   ```bash
   # Nginx配置示例
   server {
     listen 80;
     server_name your-domain.com;
     
     location /mcp {
       proxy_pass http://localhost:5678;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
     }
   }
   ```

3. **在Dify配置工具**：
   - 登录Dify管理面板
   - 导航至"工具管理" → "添加工具" → "自定义工具"
   - 填写以下信息：
     * 工具名称：`mytools`
     * 工具描述：简要描述您的工具集
     * API URL：`https://your-domain.com/mcp`
     * 认证类型：选择适合的身份验证方式
     * 授权信息：填写相应的认证信息
   - 保存配置后即可在Dify应用中使用

4. **在Dify应用中使用**：
   - 创建或编辑应用
   - 在"工具"部分启用您添加的MCP工具
   - 保存并发布应用

### Docker部署

使用Docker容器化部署MCP服务：

1. **创建Dockerfile**：
   ```dockerfile
   FROM python:3.11-slim
   
   WORKDIR /app
   
   COPY mcp_framework/ /app/mcp_framework/
   COPY requirements.txt /app/
   
   RUN pip install --no-cache-dir -r requirements.txt
   
   ENV MCP_TRANSPORT=http
   ENV MCP_HTTP_HOST=0.0.0.0
   ENV MCP_HTTP_PORT=5678
   
   CMD ["python", "-m", "mcp_framework"]
   ```

2. **构建镜像**：
   ```bash
   docker build -t mcp-framework:latest .
   ```

3. **运行容器**：
   ```bash
   docker run -p 5678:5678 -e MCP_TRANSPORT=http mcp-framework:latest
   ```

## 业务系统集成

本框架支持与业务系统对接，提供结构化的方式来访问业务API并将其作为MCP工具暴露给AI助手。以下是对接业务系统的开发步骤和最佳实践。

### 业务对接架构

```
mcp_framework/
├── business/                  # 业务逻辑模块
│   ├── __init__.py            # 模块初始化
│   ├── api_client.py          # DSP API客户端
│   ├── analysis/              # 分析报表模块
│   │   └── reports.py         # 多维分析报表功能
│   ├── plans/                 # 计划相关模块
│   │   └── plans.py           # 计划业务逻辑
│   ├── project/               # 项目配置模块
│   │   └── config.py          # 项目配置相关功能
│   ├── flow/                  # 流程相关模块
│   │   └── flow.py            # 流程业务逻辑
│   └── market/                # 市场投放模块
│       └── accounts.py        # 账户相关功能
└── mcp_tools/
    └── dsp_tools.py           # DSP系统MCP工具封装
```

各模块功能说明：

1. **api_client.py**: 提供统一的业务API调用接口，处理认证、请求构建和错误处理
2. **analysis**: 分析报表模块，提供多维分析报表相关功能
3. **plans**: 计划管理模块，提供计划查询、配置等功能
4. **project**: 项目配置模块，提供项目自定义指标配置等功能
5. **flow**: 流程管理模块，提供工作流相关功能
6. **market**: 市场投放模块，提供账户管理、市场投放相关功能

### 开发流程示例：添加"获取计划投放信息"功能

以下是开发一个新的业务功能的完整流程，以"获取计划投放信息"为例：

#### 1. 了解API规范

首先了解业务系统的API规范：

- 接口URL: `https://openapi.growone.sg/mcp/v1/engine/plans/get`
- 请求方式: POST
- 请求参数: JSON格式，包含`planId`
- 返回格式: JSON，包含状态码、消息和数据

#### 2. 配置API连接信息

在`mcp_framework/config/settings.py`的默认配置中确保有如下设置：

```python
# 业务API配置
"BUSINESS_API_BASE_URL": "https://openapi.growone.sg",
"BUSINESS_API_VERSION": "v1",
"BUSINESS_API_ACCESS_TOKEN": "",
"BUSINESS_API_TIMEOUT": 30.0,
```

#### 3. 实现业务逻辑层

在`mcp_framework/business/plans/plans.py`中实现业务逻辑：

```python
async def get_plan_info(plan_id: str) -> Dict[str, Any]:
    """获取计划投放信息
    
    Args:
        plan_id: 计划ID
        
    Returns:
        计划详情数据
    """
    params = {
        "planId": plan_id
    }
    
    # 调用API客户端发送请求
    result = await api_client.request("plans", "get", params)
    
    if not result.get("success"):
        logger.error(f"获取计划信息失败: {result.get('error')}")
    
    return result
```

这个函数执行以下步骤：
- 构建请求参数
- 调用API客户端发送请求
- 处理响应和错误
- 返回标准化的结果

#### 4. 创建MCP工具

在`mcp_framework/mcp_tools/dsp_tools.py`中，将业务逻辑包装为MCP工具：

```python
@mcp.tool()
async def get_plan_detail(plan_id: str) -> Dict[str, Any]:
    """获取营销计划详情
    
    Args:
        plan_id: 计划ID
        
    Returns:
        计划详细信息
    """
    result = await plans_api.get_plan_info(plan_id)
    return result
```

使用`@mcp.tool()`装饰器将函数注册为MCP工具，并添加详细的文档字符串。

#### 5. 测试工具

启动MCP服务器，可以通过以下方式测试：

```bash
# 确保配置中有正确的API访问令牌
export BUSINESS_API_ACCESS_TOKEN="your_token_here"

# 启动MCP服务器
python -m mcp_framework
```

在客户端（如Cursor或Claude）中，可以直接调用`get_plan_detail`工具：

```
我想查看计划ID为"PLAN123"的详细信息
```

AI助手将调用`get_plan_detail("PLAN123")`并展示结果。

### 业务系统对接的最佳实践

1. **分层设计**：保持API客户端、业务逻辑和MCP工具的清晰分离。
2. **详细文档**：为每个函数提供完整的文档字符串，包括参数和返回值的描述。
3. **错误处理**：始终捕获和记录异常，返回友好的错误消息。
4. **统一返回格式**：保持一致的JSON结构，便于AI助手理解和展示。
5. **避免业务逻辑复杂化**：MCP工具应该简单地调用业务逻辑，复杂处理应在业务层完成。

通过这种方式，可以轻松地将业务系统的任何功能集成到MCP框架中，使AI助手能够访问和操作业务数据。

### 已实现的DSP工具

框架目前已实现的DSP系统工具包括：

1. **账户管理**
   - `get_marketing_accounts` - 获取营销账户列表
   - `get_account_detail` - 获取账户详情

2. **计划管理**
   - `get_marketing_plans` - 获取营销计划列表
   - `get_plan_detail` - 获取计划详情

3. **诊断分析**
   - `get_plan_diagnosis` - 获取计划诊断数据，包含请求量、竞价成功量及40种过滤原因的统计数据

可以通过添加新的业务逻辑模块和MCP工具，轻松扩展支持更多DSP系统功能。

### 已实现的AIGC工具

框架已集成AIGC视频生成能力，提供以下工具：

1. **视频生成**
   - `generate_video` - 异步提交视频生成任务，基于产品图片和脚本生成营销视频
   - `check_video_task_status` - 查询视频生成任务的状态和结果
   - `generate_video_and_wait` - 同步生成视频并等待完成（一步到位）

**典型使用流程：**

方式1：异步处理（推荐）
```python
# 1. 提交视频生成任务
result = await generate_video(
    product_image_url="https://example.com/product.jpg",
    video_title="Amazing Product",
    video_content="This is an amazing product",
    narration_script="欢迎了解我们的新产品"
)
task_id = result['task_id']

# 2. 查询任务状态
status = await check_video_task_status(task_id)

# 3. 获取视频URL（当status为success时）
video_url = status['video_url']
```

方式2：同步等待
```python
# 一步完成，自动等待结果
result = await generate_video_and_wait(
    product_image_url="https://example.com/product.jpg",
    video_title="Amazing Product",
    video_content="This is an amazing product",
    narration_script="欢迎了解我们的新产品",
    max_wait_minutes=10
)
video_url = result['video_url']
```

**详细文档：** [AIGC工具使用指南](aigc_tools_guide.md)

## 许可证

MIT