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      ┌─────────────┐    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_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 获取节点关系

任务管理工具

工具 说明
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 桌面应用中手动解锁
  • 是根节点 → 根节点不可删除

更新日志

v2.6.9

  • ✨ kg_list_nodes 支持 status/minEdges/maxEdges 过滤
  • 🗑️ 移除 kg_find_orphans (用 kg_list_nodes(maxEdges: 0) 替代)

v2.5.0

  • ✨ 新增 CLI init 命令，自动安装工作流模板
  • ✨ 支持 Codex 模式 (--codex)
  • 📦 构建时自动复制模板

v2.4.0

  • 🛡️ kg_lock_node 只能锁定，解锁需前端手动操作
  • ⚡ 后端自动记录操作日志

v2.3.0

  • 新增任务管理功能
  • 添加文件锁防止并发写入

许可证

MIT License

相关链接