AI导哈

知识管理服务器

一个为编程代理（如Claude Code、Codex、Gemini）提供项目特定知识管理的MCP服务器，采用stdio传输和YAML存储优化LLM效率。

  • by sephriot
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 sephriot/knowledge-mcp

使用说明

知识MCP服务器

MCP服务器为编码代理（Claude Code、Codex、Gemini）提供项目特定的知识管理。用途 stdio传输 和 基于YAML的存储 以获得最佳的LLM效率。

类似概念的更好版本： 阿特拉斯mcp

本地第一设计：每个项目都有自己的 .knowledge 可以提交到git的目录。

备注：PyPI上还有另一个同名的无关项目。这个项目是 未发布到PyPI。仅从GitHub安装。

快速开始

使用知识mcp的最简单方法是通过 uvx （无需安装）。

克劳德代码

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "knowledge-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sephriot/knowledge-mcp",
        "knowledge-mcp",
        "--data-path",
        ".knowledge"
      ]
    }
  }
}

或者通过CLI全局添加：

claude mcp add knowledge-mcp -- uvx --from git+https://github.com/sephriot/knowledge-mcp knowledge-mcp

验证它是否有效：

claude mcp list

双子座

增添 ~/.gemini/settings.json:

{
  "mcpServers": {
    "knowledge-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sephriot/knowledge-mcp",
        "knowledge-mcp",
        "--data-path",
        ".knowledge"
      ]
    }
  }
}

替代安装

如果您更喜欢在本地安装而不是使用uvx：

# Clone and install
git clone https://github.com/sephriot/knowledge-mcp
cd knowledge-mcp
pip install -e .

# Then configure your MCP client to use the installed command
claude mcp add knowledge-mcp -- knowledge-mcp --data-path .knowledge

CLI选项

选项 描述
--data-path PATH 知识存储目录的路径（默认： .knowledge 或 KNOWLEDGE_MCP_PATH env）
--persist-popularity 每次原子检索时，将流行度计数保存到磁盘

独立运行

# Default: uses .knowledge in current directory
knowledge-mcp

# Custom data path
knowledge-mcp --data-path /path/to/knowledge

# Via environment variable
KNOWLEDGE_MCP_PATH=./my-knowledge knowledge-mcp

人气追踪

服务器跟踪通过以下方式检索每个原子的频率 get_atom该流行度得分影响搜索排名（更受欢迎的原子排名更高）。默认情况下，流行度仅在内存中跟踪，并在发生其他索引更改时持续存在。

使用 --persist-popularity 每次检索时立即将流行度计数写入磁盘。这在以下情况下很有用：

  • 运行内存计数将丢失的短期会话
  • 您希望保证使用模式的持久性
  • 多个服务器实例共享同一存储

注意：启用此选项会增加磁盘写入。对于大多数用例，默认行为就足够了。

存储结构

.knowledge/
├── index.yaml           # Fast lookup index (denormalized metadata)
└── atoms/
    ├── K-000001.yaml    # Knowledge atom (YAML)
    ├── K-000002.yaml
    └── ...

知识原子类型

类型 描述
fact 已验证有关代码库的信息
decision 建筑或设计决策
procedure 分步流程或工作流
pattern 可重用代码模式或实践
gotcha 常见陷阱或棘手行为
glossary 特定领域术语
snippet 可重用代码片段

可用工具

核心工具

工具 说明
search 按标题、标签、内容搜索原子
upsert 创建或更新知识原子

知识组织

工具 说明
list_atoms 列出具有可选过滤功能的原子
get_atom 按ID获取完整的原子内容
delete_atom 弃用原子（将状态设置为弃用）
purge_atom 永久删除原子（无法撤消）
list_all_ids 列出存储器中的所有原子ID

批量操作

工具 说明
export_all 将所有知识导出为单个JSON
rebuild_index 从atom文件重建index.yaml

效用

工具 说明
get_summary 按类型/标签/语言分组的摘要
get_next_id 获取下一个可用的K-XXXXXX ID

示例用法

创建知识原子

{
  "tool": "upsert",
  "arguments": {
    "title": "Error Handling Pattern",
    "type": "pattern",
    "status": "active",
    "confidence": "high",
    "language": "typescript",
    "tags": ["error-handling", "async"],
    "summary": "Centralized async error handling using Result types.",
    "details": "Always wrap async operations in try-catch with specific error types...",
    "pitfalls": ["Don't catch generic errors without re-throwing"],
    "sources": [
      {"kind": "repo_path", "ref": "src/utils/errors.ts"}
    ]
  }
}

搜索知识

{
  "tool": "search",
  "arguments": {
    "query": ["error", "handling"],
    "types": ["pattern", "gotcha"],
    "language": "typescript",
    "limit": 5
  }
}

深度内容搜索

使用 include_content: true 在atom内容（摘要和详细信息）中搜索，而不仅仅是标题和标签：

{
  "tool": "search",
  "arguments": {
    "query": ["exponential", "backoff"],
    "include_content": true
  }
}

文件路径搜索

使用 file_path 查找与特定文件相关的原子。支持层次匹配：

{
  "tool": "search",
  "arguments": {
    "file_path": "src/utils/errors.ts"
  }
}

或搜索多个文件：

{
  "tool": "search",
  "arguments": {
    "file_path": ["src/api/client.ts", "src/api/server.ts"]
  }
}

评分：精确匹配（+100）>父目录（+50衰减）>子目录匹配（+30）。

原子场参考

字段 必填 描述
id 是 唯一ID（K-XXXXXX格式）
title 是 简短的描述性标题
type 是 事实、决定、程序、模式、gotcha、术语表、摘录
status 是 活动、草稿、已弃用
confidence 是 高、中、低
summary 是 主要内容摘要
details 否 详细说明或代码
pitfalls 否 潜在陷阱列表
language 否 编程语言
tags 无 搜索关键字
sources 否 引用（报告路径、票证、url、对话）
links 否 关系（依赖、参见、矛盾）

AI助手集成

为确保您的AI助手（Claude、Gemini、Codex等）自动使用知识mcp，请将系统提示添加到助手的配置文件中。

双子座

附加以下内容 SYSTEM_PROMPT.md 到 ~/.gemini/GEMINI.md.

克劳德代码

附加以下内容 SYSTEM_PROMPT.md 到 ~/.claude/CLAUDE.md 或者你的项目 CLAUDE.md.

其他助理

复制以下内容 SYSTEM_PROMPT.md 转到助手的系统提示或配置文件。

这确保了助理将：

  1. 在开始任务之前搜索现有知识
  2. 将相关知识应用于决策
  3. 发现可重用知识时创建新原子
  4. 在回复中引用知识用法

发展

需求

  • Python 3.11+
  • 依赖关系：mcp、pyyaml、pydantic

运行测试

pip install -e ".[dev]"
pytest tests/

类型检查

mypy src/knowledge_mcp

许可证

麻省理工学院

相关 MCP