📖 简介
本手册提供了如何将 rongchuan.ai API 集成为 MCP（Model Context Protocol）工具的完整指导。
✅ 好消息
rongchuan.ai API 已完全修复并通过所有测试，可以完美集成为 MCP 工具！
rongchuan.ai API 已完全修复并通过所有测试，可以完美集成为 MCP 工具！
什么是 MCP?
MCP（Model Context Protocol）是一个开放标准协议，允许应用程序与 AI 模型进行交互。它定义了工具的调用方式、参数传递和结果返回的标准格式。
本手册适用于
- 想要集成 rongchuan.ai API 的开发者
- 需要理解 MCP 工具定义的工程师
- 正在构建 AI 应用的团队
🚀 快速开始（3 步）
步骤 1: 准备环境
cd /Users/qmk/Desktop/NewAPI文档 python3 --version # Python 3.7+
步骤 2: 查看示例
python3 test_mcp_integration.py
这会显示 RongChuanAIMCPTool 的实际工作示例。
步骤 3: 在代码中使用
from test_mcp_integration import RongChuanAIMCPTool
# 初始化工具
tool = RongChuanAIMCPTool(api_key="sk-...")
# 进行聊天
result = tool.chat([
{"role": "user", "content": "Hello, MCP!"}
])
# 获取结果
if result["success"]:
print(result["content"])
else:
print(f"错误: {result['error']}")💡 核心概念
API vs MCP 工具
| 特性 | rongchuan.ai API | MCP 工具 |
|---|---|---|
| 协议类型 | OpenAI 兼容 REST API | MCP 标准工具定义 |
| 访问方式 | HTTP 请求 | 工具调用接口 |
| 集成方式 | 直接 API 调用 | 通过包装类（RongChuanAIMCPTool） |
| 使用场景 | 独立应用 | MCP 客户端、Claude、Agent |
RongChuanAIMCPTool 类
这是一个包装类，将 rongchuan.ai API 转换为标准 MCP 工具。
提供的方法：
•
•
•
•
•
chat(messages) - 单轮聊天•
multi_turn_chat(messages) - 多轮对话•
batch_chat(questions) - 批量处理•
get_mcp_tool_definition() - 获取工具定义
📁 文件说明
⭐ MCP测试报告.md
详细的测试结果分析和集成最佳实践指南。
内容： 测试结果、API 能力评估、推荐配置
阅读时间： 5-10 分钟
⭐ test_mcp_integration.py
完整的 MCP 工具集成实现，可直接使用。
包含： RongChuanAIMCPTool 类、示例代码
用途： 参考实现、导入使用
test_mcp_client.py
诊断工具，验证 API 的 MCP 兼容性。
用途： 故障诊断、功能验证
test_mcp_format.py
格式验证工具，检查请求/响应格式。
用途： 深入理解格式兼容性
🎯 常见场景
场景 1: 单轮聊天
from test_mcp_integration import RongChuanAIMCPTool
tool = RongChuanAIMCPTool(api_key="sk-...")
result = tool.chat([
{"role": "user", "content": "What is AI?"}
])
print(result["content"])场景 2: 多轮对话
messages = [
{"role": "system", "content": "You are a Python expert"},
{"role": "user", "content": "How to read a file?"}
]
# First turn
result1 = tool.multi_turn_chat(messages)
print("Assistant:", result1["content"])
# Continue conversation
messages.append({"role": "user", "content": "How to write a file?"})
result2 = tool.multi_turn_chat(messages)
print("Assistant:", result2["content"])场景 3: 批量处理
questions = [
"What is Python?",
"What is JavaScript?",
"What is Rust?"
]
results = tool.batch_chat(questions)
for q, r in zip(questions, results):
print(f"Q: {q}")
print(f"A: {r['content']}\n")场景 4: 获取工具定义
tool_def = RongChuanAIMCPTool.get_mcp_tool_definition() import json print(json.dumps(tool_def, indent=2))
🔌 集成步骤
步骤 1: 导入工具类
from test_mcp_integration import RongChuanAIMCPTool
步骤 2: 初始化实例
tool = RongChuanAIMCPTool(
api_key="your-api-key-here",
model="gpt-5" # 可选，默认 gpt-5
)步骤 3: 调用方法
# 选择适合你的场景 result = tool.chat(messages) # 单轮 result = tool.multi_turn_chat(messages) # 多轮 results = tool.batch_chat(questions) # 批量
步骤 4: 处理结果
if result["success"]:
print("Response:", result["content"])
print("Tokens:", result.get("tokens", {}))
else:
print("Error:", result.get("error"))功能检查清单
- 单轮聊天
- 多轮对话
- 系统提示
- 参数控制（temperature、max_tokens 等）
- Token 计数
- 错误处理
- 批量处理
- 多个模型支持
📚 API 参考
RongChuanAIMCPTool 类
构造函数
RongChuanAIMCPTool(api_key, model="gpt-5")
| 参数 | 类型 | 描述 |
|---|---|---|
| api_key | str | rongchuan.ai API 密钥 |
| model | str | 模型名称，默认 "gpt-5" |
chat() 方法
chat(messages, model=None, max_tokens=200, temperature=0.7)
进行单轮聊天对话。
| 参数 | 类型 | 描述 |
|---|---|---|
| messages | list | 消息列表，包含 role 和 content |
| model | str | 可选，覆盖默认模型 |
| max_tokens | int | 最大返回 token 数，默认 200 |
| temperature | float | 温度参数 0-2，默认 0.7 |
返回值
{
"success": bool,
"content": str,
"model": str,
"tokens": {
"prompt_tokens": int,
"completion_tokens": int,
"total_tokens": int
},
"error": str # 仅在失败时出现
}multi_turn_chat() 方法
支持多轮对话，保留对话历史。
multi_turn_chat(messages, **kwargs)
batch_chat() 方法
批量处理多个问题。
batch_chat(questions, model=None, max_tokens=200)
get_mcp_tool_definition() 方法 (静态)
获取 MCP 工具定义。
tool_def = RongChuanAIMCPTool.get_mcp_tool_definition()
支持的模型
- gpt-5（推荐）
- gpt-5.2
- gpt-4o-mini
- gpt-4.1-mini
MCP 工具定义示例
{
"type": "function",
"function": {
"name": "rongchuan_ai_chat",
"description": "使用 rongchuan.ai API 进行 AI 对话",
"parameters": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"description": "聊天消息列表"
},
"model": {
"type": "string",
"enum": ["gpt-5", "gpt-5.2", "gpt-4o-mini"]
},
"max_tokens": {
"type": "integer",
"default": 200
}
},
"required": ["messages"]
}
}
}🔍 故障排查
问题 1: ImportError
错误：
ImportError: No module named 'test_mcp_integration'
解决方案：
cd /Users/qmk/Desktop/NewAPI文档
python3 -c "from test_mcp_integration import RongChuanAIMCPTool; print('OK')"问题 2: 返回空内容
解决方案： 检查 result["success"] 状态
result = tool.chat([{"role": "user", "content": "Hello"}])
if result["success"]:
print(result["content"])
else:
print(f"错误: {result['error']}")问题 3: API Key 不正确
解决方案： 验证 API Key 是否有效
python3 -c "
from test_mcp_integration import RongChuanAIMCPTool
tool = RongChuanAIMCPTool('sk-your-key-here')
result = tool.chat([{'role': 'user', 'content': 'test'}])
print('成功' if result['success'] else result.get('error'))
"问题 4: 网络超时
原因： API 服务响应缓慢或网络连接问题
解决方案：
- 检查网络连接
- 增加超时时间
- 重试请求
诊断工具
运行完整诊断来检查 API 的 MCP 支持：
python3 test_mcp_client.py
❓ 常见问题
Q1: MCP 是什么？
MCP（Model Context Protocol）是一个开放标准协议，用于定义 AI 工具的调用接口和参数。它允许应用程序以统一的方式与 AI 模型交互。
Q2: rongchuan.ai 是 MCP 服务器吗？
不是。 rongchuan.ai 是一个 OpenAI 兼容的 REST API。但它可以通过 RongChuanAIMCPTool 包装类集成为 MCP 工具。
Q3: 如何选择模型？
推荐使用 gpt-5，这是性能最好的模型。如果需要轻量级选项，可以使用 gpt-4o-mini。
Q4: 支持多轮对话吗？
是的。 使用 multi_turn_chat() 方法进行多轮对话，对话历史会自动保留。
Q5: 如何批量处理问题？
使用 batch_chat() 方法，传入问题列表即可批量处理。
Q6: Token 是什么？
Token 是 API 计费的基本单位。通常 1 Token ≈ 4 个字符。返回的 result 包含 prompt_tokens、completion_tokens 和 total_tokens。
Q7: 如何处理错误？
始终检查 result["success"] 来判断请求是否成功，使用 result["error"] 获取错误信息。
Q8: 可以在生产环境使用吗？
是的。 API 已通过所有测试（6/6），状态为"生产就绪"。
✨ 最佳实践
1. 错误处理
try:
result = tool.chat(messages)
if result["success"]:
return result["content"]
else:
raise Exception(f"API Error: {result['error']}")
except Exception as e:
# Handle error appropriately
print(f"Failed: {e}")
return None2. 性能优化
- 使用 batch_chat() 批量处理多个请求
- 设置合理的 max_tokens 限制
- 使用缓存保存常见问题的答案
3. API Key 安全
- 不要在代码中硬编码 API Key
- 使用环境变量存储敏感信息
- 定期轮换 API Key
4. 模型选择
| 场景 | 推荐模型 | 原因 |
|---|---|---|
| 通用场景 | gpt-5 | 最佳性能和准确性 |
| 轻量级应用 | gpt-4o-mini | 更快更便宜 |
| 高精度任务 | gpt-5.2 | 最高准确度 |