Package Exports

@ppdocs/mcp
@ppdocs/mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ppdocs/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@ppdocs/mcp

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

概述

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

当前 MCP 采用 flowchart-first 模型：节点、关系、绑定文件、任务关联和节点文档统一收敛到 kg_flowchart(action:"...")，不再维护独立的 kg_doc / kg_search / kg_create_node 一组旧接口。

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

核心功能

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

快速开始

1. 安装

npm install -g @ppdocs/mcp

2. 初始化项目

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

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

4. 获取 API URL

打开 ppdocs 桌面应用
选择一个项目 → 点击设置图标
复制 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_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`	删除子图

常用示例

# 搜索相关节点
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: 连接失败怎么办？

确保 ppdocs 桌面应用正在运行
检查端口是否正确 (默认 20001)
验证 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/mcp

Package Exports

Readme

@ppdocs/mcp

概述

核心功能

快速开始

1. 安装

2. 初始化项目

3. 配置 Claude Desktop

4. 获取 API URL

CLI 命令

工具列表

核心工具

kg_flowchart actions

常用示例

节点类型

节点状态

环境变量

常见问题

更新日志

v3.3.0

v3.2.36

v2.5.0

v2.3.0

许可证

相关链接

`kg_flowchart` actions