JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 178
  • Score
    100M100P100Q148268F
  • License MIT

ppdocs MCP Server - Knowledge Graph for Claude

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 拥有项目知识图谱记忆

npm version

概述

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": {
      "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_init 初始化项目连接与上下文
kg_status 查看项目仪表盘与流程图概况
kg_flowchart 统一的知识图谱入口，负责查询、更新、关系分析
kg_workflow Markdown 文档工作流管理
kg_task 任务管理
kg_files 项目文件读写/上传下载
kg_discuss 讨论区
kg_meeting 多 AI 协作会议
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: 连接失败怎么办？

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

Q: 节点无法删除？

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

更新日志

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

相关链接