mirror of
https://github.com/nagisa77/OpenIsle.git
synced 2026-02-24 23:20:49 +08:00
52 lines
1.7 KiB
Markdown
52 lines
1.7 KiB
Markdown
# MCP 服务协作指引
|
||
|
||
## 1) 适用范围
|
||
|
||
- 作用于 `mcp/` 目录及其子目录。
|
||
- 本模块对外提供 MCP tools，接口兼容性要求高。
|
||
|
||
## 2) 模块结构
|
||
|
||
- `src/openisle_mcp/server.py`：Tool 定义与请求处理入口。
|
||
- `src/openisle_mcp/search_client.py`：调用 OpenIsle 后端 HTTP API。
|
||
- `src/openisle_mcp/schemas.py`：Pydantic 数据契约。
|
||
- `src/openisle_mcp/config.py`：运行配置与环境变量读取。
|
||
|
||
## 3) 变更原则
|
||
|
||
- Tool 名称默认视为稳定契约，非必要不重命名。
|
||
- 后端接口字段变化时，优先同步 `schemas.py`，再调整 `server.py` 映射。
|
||
- 对认证接口保持“显式失败”：
|
||
- 缺 token、401、403 需给出可理解错误信息。
|
||
- 避免吞掉异常上下文，保留足够定位信息（HTTP 状态、接口语义）。
|
||
|
||
## 4) 与后端契约同步
|
||
|
||
- 高风险同步点：
|
||
- `create_post`
|
||
- `reply_to_post`
|
||
- `reply_to_comment`
|
||
- `list_unread_messages`
|
||
- `mark_notifications_read`
|
||
- 若后端响应结构改动，需同步：
|
||
- `search_client.py` 的解析逻辑
|
||
- `schemas.py` 的校验模型
|
||
- `README.md` 的 tool 说明（如有新增/删减）
|
||
|
||
## 5) 配置规则
|
||
|
||
- 环境变量统一使用 `OPENISLE_MCP_*` 前缀。
|
||
- 保持默认值可本地运行（如 `http://localhost:8080` 场景）。
|
||
- 不在代码中硬编码私密 token。
|
||
|
||
## 6) 验证建议
|
||
|
||
- 安装校验：`python -m pip install -e .`
|
||
- 启动校验：`openisle-mcp`（或项目内等价启动方式）
|
||
- 如改动 schema/解析逻辑，至少完成一次真实后端联调请求。
|
||
|
||
## 7) 输出要求
|
||
|
||
- 说明变更是否影响 tool 输入/输出契约。
|
||
- 说明是否要求调用方更新（参数名、字段、错误语义）。
|