ppdocs MCP Server - Knowledge Graph for Claude
npm install @ppdocs/mcp
┌─────────────┐ MCP ┌─────────────┐ HTTP ┌─────────────┐
│ Claude AI │ ──────────── │ @ppdocs/mcp │ ────────── │ ppdocs 桌面 │
└─────────────┘ └─────────────┘ └──────┬──────┘
│
┌──────▼──────┐
│ 知识图谱 │
│ 文件存储 │
└─────────────┘
`
$3
| 功能 | 描述 |
|------|------|
| 📊 知识图谱 | 创建、更新、删除、搜索节点 |
| 🔗 依赖追踪 | 自动计算节点间的依赖关系 |
| 📝 任务管理 | 记录开发任务、进度日志、经验总结 |
| 🔍 智能搜索 | 多关键词搜索，按相关度排序 |
| 🛤️ 路径分析 | 查找两节点间的依赖路径 |
---
快速开始
$3
`bash
npm install -g @ppdocs/mcp
`
$3
`bash
npx @ppdocs/mcp init -p <项目ID> -k <密钥>
`
这会自动：
- 创建 .ppdocs 配置文件
- 创建 .mcp.json MCP 配置
- 安装工作流模板到 .claude/
$3
在 Claude Desktop 配置文件中添加：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
`json
{
"mcpServers": {
"ppdocs": {
"command": "npx",
"args": ["-y", "@ppdocs/mcp"],
"env": {
"PPDOCS_API_URL": "http://localhost:20001/api/项目ID/密码"
}
}
}
}
`
$3
1. 打开 ppdocs 桌面应用
2. 选择一个项目 → 点击设置图标
3. 复制 MCP 连接地址
---
CLI 命令
`bash
初始化 (Claude Code 模式)
npx @ppdocs/mcp init -p -k
初始化 (Codex 模式 - 生成 AGENTS.md)
npx @ppdocs/mcp init -p -k --codex
选项
-p, --project 项目 ID (必填)
-k, --key API 密钥 (必填)
-u, --user 用户名 (可选，自动生成)
--port API 端口 (默认: 20001)
--api API 主机 (默认: localhost)
--codex Codex 模式
`
---
工具列表
$3
| 工具 | 说明 |
|------|------|
| 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 | 获取节点关系 |
$3
| 工具 | 说明 |
|------|------|
| 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 桌面应用中手动解锁
- 是根节点 → 根节点不可删除
---
更新日志
$3
- ✨ kg_list_nodes 支持 status/minEdges/maxEdges 过滤
- 🗑️ 移除 kg_find_orphans (用 kg_list_nodes(maxEdges: 0) 替代)
$3
- ✨ 新增 CLI init 命令，自动安装工作流模板
- ✨ 支持 Codex 模式 (--codex)
- 📦 构建时自动复制模板
$3
- 🛡️ kg_lock_node` 只能锁定，解锁需前端手动操作