appcan-helper-mcp 1.0.1
AppCan Helper MCP Server - 提供 AppCan 开发规则以及官方文档查询功能
License: MIT
Requires Python: >=3.8
Keywords: mcp, appcan, documentation, ai, assistant

# 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 相关商标和文档版权归正益移动互联科技股份有限公司所有。