agentmods.dev

kb-mcp-server CLAUDE.md

Development instructions for kb-mcp-server, a Python service that exposes a knowledge-base search system through MCP. A knowledge base is a collection of stored information that can be searched by questions.

In plain words
What is it for?
Building and testing a Chinese-language knowledge-base search server that reads from the existing online database service. The instructions cover setup, tenant isolation, secrets, and empty-search responses.
Why use it?
It defines the project’s security, language, logging, read-only, and step-by-step approval rules, reducing the risk of leaking data or breaking the MCP communication channel.

Instructions file

0 2mo ago A scan 1,706 tokens original MIT
View the source file code-runner-xx/kb-mcp-server
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add instructions/code-runner-xx/kb-mcp-server/claude-md
Clone the repo
git clone --depth 1 https://github.com/code-runner-xx/kb-mcp-server
Per session 1,706 This file is loaded in full into every session.
When invoked 1,706 The same file — it is already loaded in full.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.01706 $0.01706
Opus 5 $0.00853 $0.00853
Sonnet 5 $0.00341 $0.00341
Haiku 4.5 $0.00171 $0.00171

Measured 2d ago against content hash a559c0695aec, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

kb-mcp-server CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 111 lines

How it starts

The opening of the file, as written. The whole thing — 111 lines — stays where its author put it; the contents beside it link to each section on GitHub.

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  # 手测用例清单

Read the full file on GitHub · 111 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 111 lines · 1,706 tokens per session scan A a559c0695aec

Subscribe to this mod's changes

kb-mcp-server CLAUDE.md is an instructions file published in the GitHub repository code-runner-xx/kb-mcp-server (0 stars, last pushed 2mo ago), licensed MIT. It adds 1,706 tokens to every session, about $0.0085 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Data and AIRAG and vectorsResearchbge-m3chinese-llmclaude-desktopfastmcpmcppgvector
Related

Other instructions, from other repositories

opencrawling CLAUDE.md

Instructions for opencrawling/opencrawling, covering claude.md, project overview, build commands, full build (all maven modules) and run the embedding microservice (separate process).

opencrawling/opencrawling · 1,867 tokens

rag-code-mcp copilot-instructions.md

Instructions for doITmagic/rag-code-mcp, covering copilot instructions - ragcode mcp, ⚖️ the golden rule, project overview, architecture & patterns and developer workflows.

doITmagic/rag-code-mcp · 568 tokens

personal-notes-assistant CLAUDE.md

Instructions for coeusyk/personal-notes-assistant, covering personal-notes-assistant, architecture, adding a tool, milvus notes (non-obvious, bit people twice already) and running / testing locally.

coeusyk/personal-notes-assistant · 900 tokens

mybrain CLAUDE.md

Claude Code instructions for robertsfeir/mybrain, covering mybrain-mcp, project overview, tech stack, source layout and run commands.

robertsfeir/mybrain · 1,487 tokens

chroma-mcp-custom CLAUDE.md

Instructions for bryankthompson/chroma-mcp-custom, covering chroma mcp server development guide, project status documentation, current project status reference, status management commands and status integration benefits.

bryankthompson/chroma-mcp-custom · 1,499 tokens

qdrant-neo4j-crawl4ai-mcp CLAUDE.md

Instructions for BjornMelin/qdrant-neo4j-crawl4ai-mcp, covering claude.md, project overview, key architecture, build system & dependencies and primary tools.

BjornMelin/qdrant-neo4j-crawl4ai-mcp · 2,613 tokens