内容
# weclapp API 知识库 MCP
一个独立的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，用于研究 [weclapp](https://www.weclapp.com/) REST API v2。从 Cursor、Claude Desktop 或任何支持 MCP 的客户端使用它来探索实体、端点、关系和筛选语法 - 并可选地验证针对您自己的租户的读取模式。
**与 weclapp 无关。** 这是一个由社区维护的独立开源项目。
## 功能
它结合了：
- 来自 `data/openapi_v2.json` 的**离线 API 知识**：实体、端点、字段、跨模式关系、筛选语法和高效的读取计划。
- 针对一个 weclapp 租户的**有界实时探测**：只读的 GET 请求，验证计划，检查真实响应结构，并诊断 API 错误。
这不是一个 CRUD 包装器。它的主要任务是回答：*我应该如何与 weclapp API 通信，数据存储在哪里，以及如何高效地获取跨模式数据？*
知识工具无需凭证即可工作。实时探测工具需要只读的 weclapp API 令牌。
## 工具组
知识工具：
- `search_knowledge`
- `explain_entity`
- `explain_endpoint`
- `get_relationships`
- `plan_cross_entity_read`
- `explain_filter_syntax`
- `compare_approaches`
实时探测工具（仅限 GET 且有界）：
- `execute_read_plan`
- `probe_entity_sample`
- `probe_list_query`
分析和验证工具：
- `analyze_response_structure`
- `compare_to_schema`
- `validate_read_plan`
- `validate_filter`
- `diagnose_api_error`
- `check_field_presence`
参见 [docs/TOOLS.md](docs/TOOLS.md) 获取参数详细信息和使用说明。
## 要求
- Python 3.11+
- [uv](https://docs.astral.sh/uv/)（推荐）或 pip
- 可选：Docker，用于通过 `mcp-remote` 进行 SSE 传输
- 可选：用于实时探测的 weclapp API 凭证
## 快速入门
### 1. 克隆和安装
```bash
git clone https://github.com/serenmind/weclapp-api-knowledgebase-mcp.git
cd weclapp-api-knowledgebase-mcp
uv sync
```
### 2. 配置凭证（可选）
实时探测工具需要只读的 weclapp 令牌：
```bash
cp .env.example .env
# 编辑 .env 并设置 WECLAPP_BASE_URL 和 WECLAPP_API_KEY
```
### 3. 运行测试（可选）
```bash
uv run pytest
```
### 4. 连接您的 MCP 客户端
**推荐 — 使用 Cursor 的 stdio**
在您的 Cursor MCP 设置（`.cursor/mcp.json` 或 Cursor 设置 → MCP）中添加：
```json
{
"mcpServers": {
"weclapp-api-knowledge": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/weclapp-api-knowledgebase-mcp",
"run",
"weclapp-api-knowledge-mcp"
],
"env": {
"MCP_TRANSPORT": "stdio"
}
}
}
}
```
如果您需要实时探测，请在 `env` 中添加 `WECLAPP_BASE_URL` 和 `WECLAPP_API_KEY`。
**替代 — Docker + SSE**
```bash
cp .env.example .env
docker compose up --build
```
然后通过 [mcp-remote](https://www.npmjs.com/package/mcp-remote) 连接：
```json
{
"mcpServers": {
"weclapp-api-knowledge": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8080/sse",
"--transport",
"sse-first"
]
}
}
}
```
更多客户端示例：[docs/CLIENT_SETUP.md](docs/CLIENT_SETUP.md)。
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `WECLAPP_BASE_URL` | 实时探测时需要 | — | 租户 API 基址，例如 `https://your-tenant.weclapp.com/webapp/api/v2` |
| `WECLAPP_API_KEY` | 实时探测时需要 | — | 只读 API 令牌 |
| `WECLAPP_AUTH_HEADER` | 否 | `AuthenticationToken` | 认证头名称 |
| `WECLAPP_OPENAPI_PATH` | 否 | `data/openapi_v2.json` | OpenAPI 规范路径 |
| `MCP_TRANSPORT` | 否 | `stdio` | `stdio` 或 `sse` |
| `MCP_HOST` | 否 | `0.0.0.0` | SSE 绑定主机 |
| `MCP_PORT` | 否 | `8080` | SSE 绑定端口 |
| `WECLAPP_MAX_PAGE_SIZE` | 否 | `10` | 列表探测的最大行数 |
| `WECLAPP_REQUEST_TIMEOUT_SECONDS` | 否 | `30` | 实时探测的 HTTP 超时 |
## 安全模型
- 不暴露写工具。
- 实时探测仅发出 GET 请求。
- 列表探测使用 `WECLAPP_MAX_PAGE_SIZE`（默认值：10）限制 `pageSize`。
- 凭证仅从环境中读取。
- 捆绑的 OpenAPI 文件可以在 weclapp 更新 v2 时刷新。
## 刷新 OpenAPI 规范
用更新的 weclapp v2 OpenAPI 导出替换 `data/openapi_v2.json`，然后重启服务器。MCP 服务器在运行时直接读取并缓存规范。
## 开发
```bash
uv sync
uv run pytest
uv run ruff check src tests
MCP_TRANSPORT=stdio uv run weclapp-api-knowledge-mcp
```
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
