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 能够在对话中构建和查询项目知识图谱。

graph LR
    Claude[Claude AI] -->|MCP| Server[@ppdocs/mcp]
    Server -->|HTTP API| Backend[ppdocs 桌面应用]
    Backend -->|文件存储| Data[(知识图谱)]

    style Claude fill:#7c3aed,color:#fff
    style Server fill:#3b82f6,color:#fff
    style Backend fill:#10b981,color:#fff

核心功能

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

快速开始

1. 安装

npm install -g @ppdocs/mcp

2. 配置 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/密码"
      }
    }
  }
}

3. 获取 API URL

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

sequenceDiagram
    participant U as 用户
    participant App as ppdocs 桌面应用
    participant Claude as Claude Desktop

    U->>App: 1. 打开项目设置
    App->>U: 2. 显示 MCP 连接地址
    U->>Claude: 3. 配置 claude_desktop_config.json
    Claude->>App: 4. MCP 连接成功

工具列表

知识图谱工具

mindmap
  root((知识图谱))
    创建
      kg_create_node
    修改
      kg_update_node
      kg_lock_node
      kg_delete_node
    查询
      kg_list_nodes
      kg_search
      kg_find_path
      kg_find_orphans
      kg_get_relations

`kg_create_node` - 创建节点

创建一个新的知识节点。

参数	类型	必填	说明
`title`	string	✅	节点标题
`type`	enum	✅	节点类型: `logic`(逻辑/函数), `data`(数据结构), `intro`(概念介绍)
`description`	string	✅	Markdown 描述 (建议使用 Mermaid 图表 + 表格)
`signature`	string	❌	唯一签名，用于依赖匹配 (默认=title)
`tags`	string[]	❌	分类标签
`dependencies`	object[]	❌	依赖列表: `[{name: "目标签名", description: "依赖说明"}]`

示例：

Claude, 创建一个节点记录用户认证模块

`kg_update_node` - 更新节点

更新现有节点的内容（锁定节点不可更新）。

参数	类型	必填	说明
`nodeId`	string	✅	节点 ID
`title`	string	❌	新标题
`description`	string	❌	新描述
`status`	enum	❌	状态: `incomplete`, `complete`, `fixing`, `refactoring`, `deprecated`
`tags`	string[]	❌	新标签
`dependencies`	object[]	❌	新依赖列表

`kg_delete_node` - 删除节点

删除指定节点（锁定节点和根节点不可删除）。

参数	类型	必填	说明
`nodeId`	string	✅	节点 ID

`kg_lock_node` - 锁定节点

锁定节点后只能读取，不能修改或删除。

⚠️ 安全限制: AI 只能锁定节点，不能解锁。解锁需要用户在前端手动操作。

参数	类型	必填	说明
`nodeId`	string	✅	节点 ID

`kg_list_nodes` - 列出所有节点

获取项目中所有节点的概览。

无参数。

`kg_search` - 搜索节点

使用关键词搜索节点，按相关度排序返回。

参数	类型	必填	说明
`keywords`	string[]	✅	关键词列表 (OR 逻辑)
`limit`	number	❌	返回数量上限 (默认 20)

示例：

Claude, 搜索所有和数据库相关的节点

`kg_find_path` - 查找依赖路径

查找两个节点之间的依赖路径。

参数	类型	必填	说明
`startId`	string	✅	起点节点 ID
`endId`	string	✅	终点节点 ID

`kg_find_orphans` - 查找孤立节点

查找没有任何连线的孤立节点，用于清理。

无参数。

`kg_get_relations` - 获取节点关系

获取指定节点的上下游关系网络。

参数	类型	必填	说明
`nodeId`	string	✅	节点 ID

返回：

outgoing: 该节点依赖的其他节点
incoming: 依赖该节点的其他节点

任务管理工具

stateDiagram-v2
    [*] --> Active: task_create
    Active --> Active: task_add_log
    Active --> Archived: task_complete
    Archived --> [*]

    state Active {
        progress
        issue
        solution
        reference
    }

`task_create` - 创建任务

创建一个新的开发任务。

参数	类型	必填	说明
`title`	string	✅	任务标题
`description`	string	✅	任务描述 (Markdown)
`goals`	string[]	❌	目标清单
`related_nodes`	string[]	❌	关联的知识节点 ID

示例：

Claude, 创建一个任务：实现用户登录功能

`task_list` - 列出任务

列出项目中的任务。

参数	类型	必填	说明
`status`	enum	❌	筛选: `active`(进行中) 或 `archived`(已归档)

`task_get` - 获取任务详情

获取任务的完整信息，包含所有日志记录。

参数	类型	必填	说明
`taskId`	string	✅	任务 ID

`task_add_log` - 添加日志

为任务记录进展、问题、方案或参考资料。

参数	类型	必填	说明
`taskId`	string	✅	任务 ID
`log_type`	enum	✅	日志类型: `progress`, `issue`, `solution`, `reference`
`content`	string	✅	日志内容 (Markdown)

`task_complete` - 完成任务

完成任务并归档，需要填写经验总结。

参数	类型	必填	说明
`taskId`	string	✅	任务 ID
`summary`	string	✅	经验总结 (Markdown)
`difficulties`	string[]	❌	遇到的困难
`solutions`	string[]	❌	解决方案
`references`	object[]	❌	参考资料: `[{title: "标题", url: "链接"}]`

数据结构

节点类型

classDiagram
    class NodeData {
        +string id
        +string title
        +NodeType type
        +NodeStatus status
        +string signature
        +string description
        +string[] categories
        +Dependency[] dependencies
        +boolean locked
        +number x, y
    }

    class Dependency {
        +string name
        +string description
    }

    NodeData --> Dependency

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

节点状态

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

架构说明

flowchart TB
    subgraph Claude["Claude Desktop"]
        MCP[MCP 协议]
    end

    subgraph Server["@ppdocs/mcp"]
        Tools[工具注册]
        HTTP[HTTP Client]
    end

    subgraph Backend["ppdocs 桌面应用"]
        API[REST API]
        Store[文件存储]
    end

    subgraph Data["数据目录 ~/.ppdocs"]
        Projects[projects/]
        Tasks[tasks/]
        Backups[backups/]
    end

    MCP <-->|stdio| Tools
    Tools --> HTTP
    HTTP <-->|HTTP| API
    API --> Store
    Store --> Projects
    Store --> Tasks
    Store --> Backups

文件结构

~/.ppdocs/
├── projects/
│   └── {project-id}/
│       ├── meta.json      # 项目元数据
│       └── nodes/
│           └── {node-id}.json
├── tasks/
│   └── {project-id}/
│       ├── active/        # 进行中的任务
│       └── archived/      # 已归档的任务
└── backups/
    └── {project-id}/
        └── {timestamp}/

环境变量

变量	说明	示例
`PPDOCS_API_URL`	API 完整地址	`http://localhost:20001/api/myproject/abc123`
`PPDOCS_PROJECT`	项目 ID (可选)	`myproject`
`PPDOCS_KEY`	访问密钥 (可选)	`abc123`
`PPDOCS_USER`	用户名 (可选)	`developer`
`PPDOCS_PORT`	API 端口 (可选)	`20001`
`PPDOCS_HOST`	API 主机 (可选)	`localhost`

配置文件

也可以在项目根目录创建 .ppdocs 文件：

{
  "project": "my-project",
  "key": "abc123",
  "user": "developer",
  "port": 20001,
  "api": "localhost"
}

常见问题

Q: 连接失败怎么办？

确保 ppdocs 桌面应用正在运行
检查端口是否正确 (默认 20001)
验证 API URL 格式: http://localhost:PORT/api/项目ID/密码

Q: 节点无法删除？

可能的原因：

节点被锁定 → 在 ppdocs 桌面应用中手动解锁
是根节点 (isOrigin=true) → 根节点不可删除

Q: 如何备份数据？

桌面应用: 设置 → 数据管理 → 导出全部项目
手动备份: 复制 ~/.ppdocs/ 目录

更新日志

v2.4.0

🛡️ 安全增强：kg_lock_node 只能锁定，解锁需前端手动操作
⚡ 日志系统重构：后端自动记录操作日志，无需 AI 主动调用
🐛 修复画布缩放闪烁问题

v2.3.0

新增任务管理功能 (task_create, task_complete 等)
优化搜索算法
添加文件锁防止并发写入

v2.2.0

从文件存储切换到 HTTP API
支持多用户协作

v2.0.0

初始 MCP 服务器版本

许可证

MIT License

@ppdocs/mcp

Package Exports

Readme

@ppdocs/mcp

概述

核心功能

快速开始

1. 安装

2. 配置 Claude Desktop

3. 获取 API URL

工具列表

知识图谱工具

kg_create_node - 创建节点

kg_update_node - 更新节点

kg_delete_node - 删除节点

kg_lock_node - 锁定节点

kg_list_nodes - 列出所有节点

kg_search - 搜索节点

kg_find_path - 查找依赖路径

kg_find_orphans - 查找孤立节点

kg_get_relations - 获取节点关系

任务管理工具

task_create - 创建任务

task_list - 列出任务

task_get - 获取任务详情

task_add_log - 添加日志

task_complete - 完成任务

数据结构

节点类型

节点状态

架构说明

文件结构

环境变量

配置文件

常见问题

Q: 连接失败怎么办？

Q: 节点无法删除？

Q: 如何备份数据？

更新日志

v2.4.0

v2.3.0

v2.2.0

v2.0.0

许可证

相关链接

`kg_create_node` - 创建节点

`kg_update_node` - 更新节点

`kg_delete_node` - 删除节点

`kg_lock_node` - 锁定节点

`kg_list_nodes` - 列出所有节点

`kg_search` - 搜索节点

`kg_find_path` - 查找依赖路径

`kg_find_orphans` - 查找孤立节点

`kg_get_relations` - 获取节点关系

`task_create` - 创建任务

`task_list` - 列出任务

`task_get` - 获取任务详情

`task_add_log` - 添加日志

`task_complete` - 完成任务