AppCan Helper MCP Server
这是一个使用 FastMCP 构建的 AppCan 助手 MCP 服务器，提供基础工具和 AppCan 官方文档查询功能。
🤖 AI 使用指南
如何向 AI 说明 MCP 使用方法
本 MCP 服务通过以下方式向 AI 提供使用说明：
1. 详细的工具描述（Docstring）
每个工具都包含完整的类型注解和文档字符串，AI可以通过这些信息了解：
- 工具的功能和用途
- 参数类型和说明
- 返回值格式
- 使用示例
2. 提示词系统（Prompt）
使用 @mcp.prompt 装饰器提供的 help_prompt 包含：
- 所有工具的完整列表
- 详细的参数说明
- 实际使用示例
- 最佳实践建议
- 常见使用场景
3. 智能返回格式
所有工具返回结果都采用：
- 结构化的文本格式
- 清晰的状态标识（✅❌🔍📚等）
- 友好的错误提示
- 操作建议和下一步指导
📋 AI 调用示例
# AI 可以通过以下方式获取帮助信息
result = await client.get_prompt("help_prompt")
# 然后根据信息调用具体工具
result = await client.call_tool("search_appcan_docs", {
"query": "插件开发"
})
功能特性
🛠️ 基础工具
greet(name)- 向用户问候get_current_time()- 获取当前时间
📚 AppCan 文档查询工具
search_appcan_docs(query, category)- 搜索 AppCan 文档内容- 支持中文模糊搜索
- 最多返回3个匹配度最高的结果
- 支持按分类筛选
get_appcan_doc_categories()- 获取所有文档分类列表get_appcan_doc_content(doc_path, page, force_refresh)- 获取指定文档内容- 返回 Markdown 格式内容
- 支持分页显示（长内容自动分页）
- 支持缓存和强制刷新
clear_appcan_docs_cache()- 清空文档缓存
安装和运行
1. 安装依赖
# 安装所有依赖
uv pip install requests beautifulsoup4 fuzzywuzzy python-levenshtein markdown
# 或者从 requirements.txt 安装
uv pip install -r requirements.txt
2. 运行服务器
方法一：使用模块运行（推荐）
# 先安装开发版本
uv pip install -e .
# 使用模块运行
python -m appcan_helper_mcp.server
方法二：使用命令行工具
# 安装后可直接使用
appcan-helper-mcp
方法三：使用 FastMCP CLI
fastmcp run appcan_helper_mcp.server:mcp
3. 测试服务器
在另一个终端运行：
python test/test_client.py
版本管理
统一版本号管理
项目采用统一的版本号管理策略，只需修改一个地方即可更新所有位置的版本号：
# 使用提供的脚本更新版本号
python scripts/update_version.py 1.2.0
# 或使用 Makefile 命令（需要安装 make）
make bump-patch # 修订版本号升级 (1.0.0 -> 1.0.1)
make bump-minor # 次版本号升级 (1.0.0 -> 1.1.0)
make bump-major # 主版本号升级 (1.0.0 -> 2.0.0)
版本号遵循 语义化版本控制规范：
- 主版本号(MAJOR)：当你做了不兼容的 API 修改
- 次版本号(MINOR)：当你做了向下兼容的功能性新增
- 修订号(PATCH)：当你做了向下兼容的问题修正
AppCan 文档查询功能详解
🔍 搜索功能
- 模糊匹配：支持关键词模糊搜索，自动匹配文档标题、分类和路径
- 中文支持：完全支持中文关键词搜索
- 智能排序：按匹配度排序，返回最相关的结果
- 结果限制：最多返回3个结果，避免信息过载
💾 缓存机制
- 自动缓存：文档内容自动缓存1天，提高访问速度
- 缓存目录：
cache/目录存储缓存文件 - 强制刷新：支持强制刷新获取最新内容
- 缓存管理：提供缓存清理工具
📖 内容处理
- Markdown 格式：自动转换为 Markdown 格式，便于阅读
- 代码保护：保留代码示例的格式和缩进
- 链接处理：自动转换相对链接为绝对链接
- 图片支持：图片以链接形式显示
📄 分页支持
- 自动分页：长内容（>50KB）自动分页显示
- 页面大小：每页15KB，适合阅读
- 导航提示：提供下一页查看提示
使用示例
基础功能
# 问候
result = await client.call_tool("greet", {"name": "张三"})
# 获取时间
result = await client.call_tool("get_current_time", {})
AppCan 文档查询
# 搜索文档
result = await client.call_tool("search_appcan_docs", {
"query": "插件开发"
})
# 获取文档分类
result = await client.call_tool("get_appcan_doc_categories", {})
# 查看具体文档
result = await client.call_tool("get_appcan_doc_content", {
"doc_path": "/IDE/summary",
"page": 1,
"force_refresh": False
})
# 强制刷新文档
result = await client.call_tool("get_appcan_doc_content", {
"doc_path": "/plugin-API/manual",
"force_refresh": True
})
# 清空缓存
result = await client.call_tool("clear_appcan_docs_cache", {})
文档分类
AppCan 文档中心包含以下主要分类：
- 入门篇：平台概述、创建APP、术语解释
- 工具篇：IDE相关功能和操作指南
- 指导篇：开发流程、证书申请、配置说明
- 基础篇：
- 引擎API（uexWindow、uexWidget等）
- JS SDK（本地存储、网络请求、UI组件等）
- 插件API（系统功能、功能扩展、界面布局等）
- UI框架（弹性盒子、基础样式等）
- 高级篇：界面开发、MVVM、组件化开发
- 案例篇：实际应用案例和解决方案
- 常见问题篇：FAQ和故障排除
项目结构
appcan-helper-mcp/
├── pyproject.toml # 包配置文件
├── README.md # 项目说明
├── LICENSE # 许可证
├── requirements.txt # 依赖列表
├── MCP_PACKAGING_GUIDE.md # 发布指南
├── src/ # 源代码目录
│ └── appcan_helper_mcp/
│ ├── __init__.py # 包初始化
│ ├── server.py # MCP 服务器主文件
│ └── utility.py # AppCan 文档工具类
└── test/ # 测试目录
├── __init__.py # 测试包初始化
└── test_client.py # 测试客户端
技术特性
🏗️ 架构设计
- 分层架构：业务逻辑与工具类分离
- 工具类封装：AppCanDocsUtility 封装所有文档处理逻辑
- 错误处理：完善的异常处理和用户友好的错误信息
- 代码规范：遵循 FastMCP 开发规范
- 模块化设计：采用标准 src 包结构，支持相对导入
🚀 性能优化
- 智能缓存：自动缓存减少网络请求
- 分页机制：大内容分页提高响应速度
- 异步处理：全异步设计，支持并发访问
- 连接复用：HTTP 连接优化
🔒 安全特性
- 输入验证：严格的参数验证
- 路径安全：防止路径遍历攻击
- 请求限制：合理的超时和重试机制
- 错误隔离：错误不会影响其他功能
开发注意事项
基本规范
- 类型注解必须完整 - FastMCP 依赖类型注解生成工具描述
- 添加清晰的 docstring - 帮助 AI 理解工具用途
- 处理异常情况 - 提供有意义的错误信息
- 使用异步客户端 - 所有客户端操作都是异步的
- 上下文管理 - 必须在
async with client:中使用客户端 - 缓存管理 - 定期清理缓存避免磁盘空间占用
- 网络超时 - 设置合理的网络请求超时时间
许可证
本项目仅供学习和研究使用。AppCan 相关商标和文档版权归正益移动互联科技股份有限公司所有。