README.md•7.93 kB
# AppCan Helper MCP Server
这是一个使用 FastMCP 构建的 AppCan 助手 MCP 服务器，提供基础工具和 AppCan 官方文档查询功能。
## 🤖 AI 使用指南
### 如何向 AI 说明 MCP 使用方法
本 MCP 服务通过以下方式向 AI 提供使用说明：
#### 1. **详细的工具描述（Docstring）**
每个工具都包含完整的类型注解和文档字符串，AI可以通过这些信息了解：
- 工具的功能和用途
- 参数类型和说明
- 返回值格式
- 使用示例
#### 2. **提示词系统（Prompt）**
使用 `@mcp.prompt` 装饰器提供的 `help_prompt` 包含：
- 所有工具的完整列表
- 详细的参数说明
- 实际使用示例
- 最佳实践建议
- 常见使用场景
#### 3. **智能返回格式**
所有工具返回结果都采用：
- 结构化的文本格式
- 清晰的状态标识（✅❌🔍📚等）
- 友好的错误提示
- 操作建议和下一步指导
### 📋 AI 调用示例
```python
# 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. 安装依赖
```bash
# 安装所有依赖
uv pip install requests beautifulsoup4 fuzzywuzzy python-levenshtein markdown
# 或者从 requirements.txt 安装
uv pip install -r requirements.txt
```
### 2. 运行服务器
#### 方法一：使用模块运行（推荐）
```bash
# 先安装开发版本
uv pip install -e .
# 使用模块运行
python -m appcan_helper_mcp.server
```
#### 方法二：使用命令行工具
```bash
# 安装后可直接使用
appcan-helper-mcp
```
#### 方法三：使用 FastMCP CLI
```bash
fastmcp run appcan_helper_mcp.server:mcp
```
### 3. 测试服务器
在另一个终端运行：
```bash
python test/test_client.py
```
## 版本管理
### 统一版本号管理
项目采用统一的版本号管理策略，只需修改一个地方即可更新所有位置的版本号：
```bash
# 使用提供的脚本更新版本号
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)
```
版本号遵循 [语义化版本控制规范](https://semver.org/lang/zh-CN/)：
- 主版本号(MAJOR)：当你做了不兼容的 API 修改
- 次版本号(MINOR)：当你做了向下兼容的功能性新增
- 修订号(PATCH)：当你做了向下兼容的问题修正
## AppCan 文档查询功能详解
### 🔍 搜索功能
- **模糊匹配**：支持关键词模糊搜索，自动匹配文档标题、分类和路径
- **中文支持**：完全支持中文关键词搜索
- **智能排序**：按匹配度排序，返回最相关的结果
- **结果限制**：最多返回3个结果，避免信息过载
### 💾 缓存机制
- **自动缓存**：文档内容自动缓存1天，提高访问速度
- **缓存目录**：`cache/` 目录存储缓存文件
- **强制刷新**：支持强制刷新获取最新内容
- **缓存管理**：提供缓存清理工具
### 📖 内容处理
- **Markdown 格式**：自动转换为 Markdown 格式，便于阅读
- **代码保护**：保留代码示例的格式和缩进
- **链接处理**：自动转换相对链接为绝对链接
- **图片支持**：图片以链接形式显示
### 📄 分页支持
- **自动分页**：长内容（>50KB）自动分页显示
- **页面大小**：每页15KB，适合阅读
- **导航提示**：提供下一页查看提示
## 使用示例
### 基础功能
```python
# 问候
result = await client.call_tool("greet", {"name": "张三"})
# 获取时间
result = await client.call_tool("get_current_time", {})
```
### AppCan 文档查询
```python
# 搜索文档
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 相关商标和文档版权归正益移动互联科技股份有限公司所有。