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

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 连接优化

🔒 安全特性

• 输入验证：严格的参数验证
• 路径安全：防止路径遍历攻击
• 请求限制：合理的超时和重试机制
• 错误隔离：错误不会影响其他功能

开发注意事项

基本规范

1. 类型注解必须完整 - FastMCP 依赖类型注解生成工具描述
2. 添加清晰的 docstring - 帮助 AI 理解工具用途
3. 处理异常情况 - 提供有意义的错误信息
4. 使用异步客户端 - 所有客户端操作都是异步的
5. 上下文管理 - 必须在 async with client: 中使用客户端
6. 缓存管理 - 定期清理缓存避免磁盘空间占用
7. 网络超时 - 设置合理的网络请求超时时间

许可证

本项目仅供学习和研究使用。AppCan 相关商标和文档版权归正益移动互联科技股份有限公司所有。