@ppdocs/mcp

Knowledge Graph MCP Server for Claude - 让 Claude 拥有项目知识图谱记忆

概述

ppdocs MCP 是一个 Model Context Protocol 服务器，让 Claude 能够在对话中构建和查询项目知识图谱。

┌─────────────┐     MCP      ┌─────────────┐    HTTP    ┌─────────────┐
│  Claude AI  │ ──────────── │ @ppdocs/mcp │ ────────── │ ppdocs 桌面 │
└─────────────┘              └─────────────┘            └──────┬──────┘
                                                               │
                                                        ┌──────▼──────┐
                                                        │  知识图谱    │
                                                        │  文件存储    │
                                                        └─────────────┘

核心功能

| 功能 | 描述 | |------|------| | 📊 知识图谱 | 创建、更新、删除、搜索节点 | | 🔗 依赖追踪 | 自动计算节点间的依赖关系 | | 📝 任务管理 | 记录开发任务、进度日志、经验总结 | | 🔍 智能搜索 | 多关键词搜索，按相关度排序 | | 🛤️ 路径分析 | 查找两节点间的依赖路径 |

快速开始

1. 安装

npm install -g @ppdocs/mcp

2. 初始化项目

npx @ppdocs/mcp init -p <项目ID> -k <密钥>

这会自动：

• 创建 .ppdocs 配置文件
• 创建 .mcp.json MCP 配置
• 安装工作流模板到 .claude/

3. 配置 Claude Desktop

在 Claude Desktop 配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ppdocs": {
      "command": "npx",
      "args": ["-y", "@ppdocs/mcp"],
      "env": {
        "PPDOCS_API_URL": "http://localhost:20001/api/项目ID/密码"
      }
    }
  }
}

4. 获取 API URL

1. 打开 ppdocs 桌面应用
2. 选择一个项目 → 点击设置图标
3. 复制 MCP 连接地址

CLI 命令

# 初始化 (Claude Code 模式)
npx @ppdocs/mcp init -p <projectId> -k <key>

# 初始化 (Codex 模式 - 生成 AGENTS.md)
npx @ppdocs/mcp init -p <projectId> -k <key> --codex

# 选项
-p, --project  项目 ID (必填)
-k, --key      API 密钥 (必填)
-u, --user     用户名 (可选，自动生成)
--port         API 端口 (默认: 20001)
--api          API 主机 (默认: localhost)
--codex        Codex 模式

工具列表

知识图谱工具

| 工具 | 说明 | |------|------| | kg_create_node | 创建知识节点 | | kg_update_node | 更新节点内容 | | kg_delete_node | 删除节点 | | kg_lock_node | 锁定节点 (AI 只能锁定，解锁需前端手动) | | kg_list_nodes | 列出节点 (支持 status/edges 过滤，maxEdges=0 查孤立节点) | | kg_search | 关键词搜索 | | kg_find_path | 查找依赖路径 | | kg_get_relations | 获取节点关系 |

任务管理工具

| 工具 | 说明 | |------|------| | task_create | 创建开发任务 | | task_list | 列出任务 | | task_get | 获取任务详情 | | task_add_log | 添加进度日志 | | task_complete | 完成任务并归档 |

节点类型

| 类型 | 说明 | 适用场景 | |------|------|----------| | logic | 逻辑/函数 | 算法、处理流程、API 接口 | | data | 数据结构 | 数据库表、配置、状态定义 | | intro | 概念介绍 | 架构说明、设计决策、术语解释 |

节点状态

| 状态 | 说明 | |------|------| | incomplete | 未完成 (默认) | | complete | 已完成 | | fixing | 修复中 | | refactoring | 重构中 | | deprecated | 已废弃 |

环境变量

| 变量 | 说明 | 示例 | |------|------|------| | PPDOCS_API_URL | API 完整地址 | http://localhost:20001/api/myproject/abc123 | | PPDOCS_PROJECT | 项目 ID | myproject | | PPDOCS_KEY | 访问密钥 | abc123 | | PPDOCS_USER | 用户名 | developer |

常见问题

Q: 连接失败怎么办？

1. 确保 ppdocs 桌面应用正在运行
2. 检查端口是否正确 (默认 20001)
3. 验证 API URL 格式

Q: 节点无法删除？

• 节点被锁定 → 在 ppdocs 桌面应用中手动解锁
• 是根节点 → 根节点不可删除

更新日志

v2.6.9

• ✨ kg_list_nodes 支持 status/minEdges/maxEdges 过滤
• 🗑️ 移除 kg_find_orphans (用 kg_list_nodes(maxEdges: 0) 替代)

v2.5.0

• ✨ 新增 CLI init 命令，自动安装工作流模板
• ✨ 支持 Codex 模式 (--codex)
• 📦 构建时自动复制模板

v2.4.0

• 🛡️ kg_lock_node 只能锁定，解锁需前端手动操作
• ⚡ 后端自动记录操作日志

v2.3.0

• 新增任务管理功能
• 添加文件锁防止并发写入

许可证

MIT License

相关链接

• ppdocs 桌面应用
• MCP 协议文档
• 问题反馈