kb-mcp-server: Instructions file for Claude Code

CLAUDE.md — kb-mcp-server 开发手册(规则书)

独立于 ai-customer-service-saas(下称 aisc)的新项目:用官方 MCP Python SDK 把 aisc 的知识库检索能力封装成标准 MCP Server。

本文件是 Claude Code 的权威执行指南。每完成一个 Step 必须停下,输出"✅ 验收方案"让用户手动测试,用户回复"通过"后才能进入下一步。禁止跳步、禁止一次性写完多个 Step。

配套文档:PLAN.md — M1-M7 分步计划与验收标准。

---

0. 项目铁律(必读)

1. stdio 模式下绝对禁止 print() 到 stdout。stdout 就是 JSON-RPC 通道,一行 print 直接把协议打挂。调试日志一律用 logging(默认走 stderr)。这是本项目第一铁律。
2. 语言:注释、commit message、工具 description 与返回文案使用简体中文;代码标识符使用英文。
3. Secrets:真实 key 永不进代码与 git,仓库只提交 .env.example 占位;日志不打印 key 和完整 chunk 内容。
4. 租户隔离:所有 SQL/RPC 固定 user_id = KB_TENANT_ID(服务端从环境变量读取写死),绝不把 tenant_id 暴露为工具参数。Service Role Key 会绕过 RLS,这正是必须显式过滤的原因。
5. 全部工具只读幂等:不暴露任何写入/删除操作(最小权限原则)。
6. 中文返回:json.dumps(..., ensure_ascii=False),否则模型看到 \uXXXX。
7. 零命中:返回明确文案「知识库中没有与该问题相关的内容」,不返回空数组(模型对空数组解读不稳定)。
8. 不要自作主张:本手册与 PLAN.md 未写清楚的细节,先在回答开头列出"❓ 待确认"问用户。
9. 不擅自升级依赖:以下文版本锁定为准,遇到不一致的 API 写法以锁定版本为准。
10. 对 aisc 零改动:本项目只读复用 aisc 的线上 Supabase RPC 与 SiliconFlow key,严禁修改 aisc 仓库的任何文件、表结构或 RPC 函数。

---

1. 版本与技术选型(锁定)

项	选择	说明
语言	Python 3.11
SDK	官方 mcp 包(内置 FastMCP),pip install "mcp[cli]"	社区另有独立 FastMCP 2.x/3.x 包,不用,以官方 SDK 为准
传输	stdio(本地)	Streamable HTTP 仅 M7 加分项
Embedding	SiliconFlow BAAI/bge-m3	1024 维,与 aisc 同源,严禁换模型(RPC 不报错但检索静默错配)
数据访问	supabase-py 调 RPC match_document_chunks	直连 aisc 线上库,零迁移
依赖管理	uv	Claude Desktop 配置里直接写 uv run
调试工具	npx @modelcontextprotocol/inspector	先 Inspector 后 Desktop,Desktop 报错信息极少

---

2. 环境变量(.env.example)

SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
SILICONFLOW_API_KEY=
KB_TENANT_ID=

KB_TENANT_ID = aisc 中你的 user_id,写死实现租户隔离。

注意:Claude Desktop 配置中的 env 字段需显式列出全部四个变量,Server 进程不继承终端环境变量。

---

3. 目录结构

kb-mcp-server/
├── server.py          # FastMCP 入口:工具/资源/提示词定义
├── kb.py              # embedding 调用 + Supabase 检索封装(纯函数,可独立测试)
├── .env.example       # 环境变量占位(真实 .env 不进 git)
├── pyproject.toml
├── README.md
├── CLAUDE.md          # 本文件
├── PLAN.md            # 分步计划
└── tests/manual_test.md  # 手测用例清单