npm package: @ppdocs/mcp
Description: ppdocs MCP Server - Knowledge Graph for Claude
Latest version: 3.13.1

# @ppdocs/mcp

> Knowledge Graph MCP Server for Claude - 让 Claude 拥有项目知识图谱记忆

[![npm version](https://badge.fury.io/js/%40ppdocs%2Fmcp.svg)](https://www.npmjs.com/package/@ppdocs/mcp)

## 概述

ppdocs MCP 是一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，让 Claude 能够在对话中构建和查询项目知识图谱。

当前 MCP 采用 `flowchart-first` 模型：节点、关系、绑定文件、任务关联和节点文档统一收敛到 `kg_flowchart(action:"...")`，不再维护独立的 `kg_doc` / `kg_search` / `kg_create_node` 一组旧接口。

```
┌─────────────┐     MCP      ┌─────────────┐    HTTP    ┌─────────────┐
│  Claude AI  │ ──────────── │ @ppdocs/mcp │ ────────── │ ppdocs 桌面 │
└─────────────┘              └─────────────┘            └──────┬──────┘
                                                               │
                                                        ┌──────▼──────┐
                                                        │  知识图谱    │
                                                        │  文件存储    │
                                                        └─────────────┘
```

### 核心功能

| 功能 | 描述 |
|------|------|
| 📊 **知识图谱** | 创建、更新、删除、搜索节点 |
| 🔗 **依赖追踪** | 自动计算节点间的依赖关系 |
| 📝 **任务管理** | 记录开发任务、进度日志、经验总结 |
| 🔍 **智能搜索** | 多关键词搜索，按相关度排序 |
| 🛤️ **路径分析** | 查找两节点间的依赖路径 |

---

## 快速开始

### 1. 安装

```bash
npm install -g @ppdocs/mcp
```

### 2. 初始化项目

```bash
npx @ppdocs/mcp init -p <项目ID> -k <密钥>
```

这会自动：
- 创建 `.ppdocs` 配置文件
- 检测工作区 IDE 配置目录，自动安装对应模板：
  - `.claude/` → Claude Code 工作流模板 + MCP 权限
  - `.cursor/` → Cursor MCP 配置 + .cursorrules
  - `.gemini/` → Antigravity MCP 配置 + AGENTS.md
  - `.kiro/` → Kiro MCP 配置 + Agent 规则
- 自动检测并注册 CLI MCP (claude/codex/gemini)

### 3. 配置 Claude Desktop

在 Claude Desktop 配置文件中添加：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ppdocs-kg": {
      "command": "npx",
      "args": ["-y", "@ppdocs/mcp"],
      "env": {
        "PPDOCS_API_URL": "http://localhost:20001/api/项目ID/密码"
      }
    }
  }
}
```

### 4. 获取 API URL

1. 打开 ppdocs 桌面应用
2. 选择一个项目 → 点击设置图标
3. 复制 **MCP 连接地址**

---

## CLI 命令

```bash
# 初始化 (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_status` | 查看项目仪表盘与流程图概况 |
| `kg_flowchart` | 统一的知识图谱入口，负责查询、更新、关系分析 |
| `kg_workflow` | Markdown 文档工作流管理 |
| `kg_task` | 任务管理 |
| `kg_ref` | 外部参考资料（URL拉取、查看、删除） |
| `code_scan` | 代码扫描 |
| `code_smart_context` | 获取符号的智能上下文 |
| `code_full_path` | 获取两个符号之间的全路径 |

### `kg_flowchart` actions

| action | 说明 |
|------|------|
| `list` | 列出所有流程图 |
| `get` | 获取指定流程图的节点与连线 |
| `search` | 按关键词搜索节点、节点文档与绑定资源 |
| `get_relations` | 查看某节点的入边/出边关系 |
| `find_path` | 查找两个节点之间的有向路径 |
| `get_node` | 获取节点详情、关联层级、绑定资源与文档 |
| `update_node` | 更新节点信息并追加节点文档版本 |
| `delete_node` | 删除节点 |
| `batch_add` | 批量新增节点与连线 |
| `bind` / `unbind` | 绑定或解绑文件、目录、文档、任务 |
| `orphans` | 检查孤立参考文档 |
| `health` | 查看节点健康度 |
| `create_chart` | 创建子图并绑定到父节点 |
| `delete_chart` | 删除子图 |

### 常用示例

```bash
# 搜索相关节点
kg_flowchart(action:"search", query:"flowchart storage")

# 查看节点详情
kg_flowchart(action:"get_node", chartId:"main", nodeId:"n_storage", expand:2, includeDoc:true, includeFiles:true)

# 追加节点文档
kg_flowchart(action:"update_node", chartId:"main", nodeId:"n_storage",
  docSummary:"补充存储层职责",
  docContent:"## 职责\n...\n## 关键流程\n...")
```

---

## 节点类型

| 类型 | 说明 | 适用场景 |
|------|------|----------|
| `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 桌面应用中手动解锁
- 是根节点 → 根节点不可删除

---

## 更新日志

### v3.3.0
- 移除 6 个低使用率工具: `kg_doc`, `kg_discuss`, `kg_meeting`, `kg_files`, `kg_projects`, `kg_pitfall`
- `kg_ref` 精简为 4 个 action: `list|get|fetch|delete`
- 所有工具描述精简，减少 token 开销
- 移除前端孤立组件: FloatingDiscussion, PitfallRecord, ImpactGraph

### v3.2.36
- 统一为 `flowchart-first` MCP 接口模型
- `kg_flowchart` 新增 `search` / `get_relations` / `find_path`
- 文档与模板改为使用 `kg_flowchart(action:"...")`，不再引用旧 `kg_doc` / `kg_search` 等独立接口

### v2.5.0
- 新增 CLI init 命令，自动安装工作流模板
- 支持 Codex 模式 (`--codex`)
- 构建时自动复制模板

### v2.3.0
- 新增任务管理功能
- 添加文件锁防止并发写入

---

## 许可证

MIT License

## 相关链接

- [ppdocs 桌面应用](https://github.com/ppdocs/ppdocs)
- [MCP 协议文档](https://modelcontextprotocol.io/)
- [问题反馈](https://github.com/ppdocs/ppdocs/issues)