OpenIsle/mcp/AGENTS.md

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 输入/输出契约。
• 说明是否要求调用方更新（参数名、字段、错误语义）。