README - CogniGraph MCP 服务器 by xsp52hz

CogniGraph MCP 服务器

更新说明

v0.1.6: 修复了通过 npx 启动时外部工具路径和依赖项的问题，提升了 npx 使用的稳定性。这是一个模型上下文协议 (MCP) 服务器，旨在使用外部命令行工具 (markmap-cli 和 @mermaid-js/mermaid-cli) 以及通过兼容 OpenAI 的 API 进行 AI 分析来生成思维导图、关系图谱和知识图谱。

此服务器设计为与各种本地 MCP 客户端兼容，包括 Claude Desktop、Cherry Studio、DeepChat 和 HyperChat。

功能

提供可通过 MCP use_mcp_tool 命令访问的多个工具：

generate_mindmap:
- 从 Markdown 文本生成思维导图。
- 直接返回生成的 HTML 或 SVG 内容。
- 输入: markdown (字符串, 必需), outputFormat (枚举: "html" | "svg", 可选, 默认: "html")。
generate_and_save_mindmap:
- 从 Markdown 文本生成思维导图。
- 将结果 (HTML 或 SVG) 保存到文件。
- 输入: markdown (字符串, 必需), outputFormat (枚举: "html" | "svg", 可选, 默认: "html"), outputDir (字符串, 可选), outputFilename (字符串, 可选)。
- 默认保存位置由 MINDMAP_DEFAULT_SAVE_DIR 环境变量确定，如果未设置则回退到用户的主目录。
generate_relationship_graph:
- 从 Mermaid 语法的文本生成关系图谱。
- 将结果 (SVG 或 PNG) 保存到文件。
- 输入: mermaid_text (字符串, 必需), outputFormat (枚举: "svg" | "png", 可选, 默认: "svg"), outputDir (字符串, 可选), outputFilename (字符串, 可选)。
- 默认保存位置由 MINDMAP_DEFAULT_SAVE_DIR 环境变量确定，如果未设置则回退到用户的主目录。
generate_knowledge_graph:
- 使用 AI 模型（通过兼容 OpenAI 的 API）分析 Markdown 文本。
- 生成表示知识图谱的 Mermaid 代码。
- 将 Mermaid 代码渲染成图像 (SVG 或 PNG) 并保存到文件。
- 输入: markdown (字符串, 必需), outputFormat (枚举: "svg" | "png", 可选, 默认: "svg"), outputDir (字符串, 可选), outputFilename (字符串, 可选), prompt (字符串, 可选), model (字符串, 可选), apiKey (字符串, 可选), baseURL (字符串, 可选)。
- 需要配置 API 访问权限（见下文）。默认保存位置遵循与其他保存工具相同的逻辑。

配置 (通过 MCP 设置 `env`)

服务器依赖 MCP 客户端设置文件（例如 mcp_settings.json）中设置的环境变量来实现某些功能：

MINDMAP_DEFAULT_SAVE_DIR: (可选) 为保存文件的工具（generate_and_save_mindmap, generate_relationship_graph, generate_knowledge_graph）设置默认输出目录（如果参数中未提供 outputDir）。
- 如果未设置此变量： 这些工具将默认保存文件到用户的主目录。generate_mindmap 工具（直接返回内容）不受影响。
OPENAI_API_KEY: (运行 generate_knowledge_graph 时必需) 用于 OpenAI 或兼容服务的 API 密钥。
- 如果未设置此变量（且未通过 apiKey 参数提供）： generate_knowledge_graph 工具将失败。其他工具不受影响。
OPENAI_BASE_URL: (可选) 兼容 OpenAI 的 API 端点的基础 URL。如果未设置，则默认为 OpenAI 官方 API。仅与 generate_knowledge_graph 相关。
OPENAI_DEFAULT_MODEL: (可选) generate_knowledge_graph 使用的默认 AI 模型名称。如果未设置，则默认为 gpt-3.5-turbo。仅与 generate_knowledge_graph 相关。

重要配置说明：

generate_mindmap 工具（工具 1）不依赖任何这些环境变量。
工具 2 和 3（generate_and_save_mindmap, generate_relationship_graph）仅依赖 MINDMAP_DEFAULT_SAVE_DIR 来确定默认保存位置。如果未设置，它们仍可工作（保存到主目录）。
工具 4（generate_knowledge_graph）必需 OPENAI_API_KEY（通过环境变量或参数）才能运行。它也会使用其他的 OPENAI_* 变量和 MINDMAP_DEFAULT_SAVE_DIR。

mcp_settings.json 配置示例：

{
  "mcpServers": {
    "cognigraph-mcp-server": { // 确保服务器名称匹配
      "command": "node",
      "args": [
        "/path/to/cognigraph-mcp-server/build/index.js" // 根据实际情况调整路径
      ],
      "env": {
        "MINDMAP_DEFAULT_SAVE_DIR": "C:\\Users\\YourUser\\Desktop",
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_BASE_URL": "http://localhost:11434/v1", // 本地 Ollama 示例
        "OPENAI_DEFAULT_MODEL": "llama3"
      },
      "disabled": false,
      "alwaysAllow": []
    }
    // ... 其他服务器
  }
}

安装设置

克隆此仓库。
进入 cognigraph-mcp-server 目录。
如上所示，在你的 MCP 客户端设置文件中配置服务器，确保服务器名称（cognigraph-mcp-server）和 args 中的路径正确。提供必要的环境变量。
重启你的 MCP 客户端以加载服务器。

使用方法

通过你的 MCP 客户端的 use_mcp_tool 功能来使用这些工具。有关参数，请参阅上面的工具描述。

以下是 Cherry Studio 的配置截图示例：

Cherry Studio 配置截图示例

通过 npx 快速使用

通过 npm 发布后，您可以使用 npx 命令快速启动此 MCP 服务器，无需手动克隆、安装依赖和构建。

确保 Node.js 和 npm 已安装。

更新您的 MCP 客户端设置文件 (mcp_settings.json 或类似文件):

将服务器配置中的 command 设置为 npx，并将 args 设置为 ["cognigraph-mcp-server"]。移除之前指向本地 build/index.js 的路径。

配置示例:

{
  "mcpServers": {
    "cognigraph-mcp-server": { // 服务器名称保持不变
      "command": "npx", // 使用 npx
      "args": [
        "cognigraph-mcp-server" // 包名
      ],
      "env": { // 环境变量保持不变
        "MINDMAP_DEFAULT_SAVE_DIR": "C:\\Users\\YourUser\\Desktop",
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_BASE_URL": "http://localhost:11434/v1",
        "OPENAI_DEFAULT_MODEL": "llama3"
      },
      "disabled": false,
      "alwaysAllow": []
    }
    // ... 其他服务器
  }
}

重启您的 MCP 客户端。 客户端现在将使用 npx 来下载（如果需要）并运行最新发布的 cognigraph-mcp-server。

注意:

使用 npx 时，服务器的环境变量（如 OPENAI_API_KEY）仍然需要通过 MCP 客户端的 env 设置来传递。
如果遇到 markmap 或 mmdc 命令找不到的问题，您可能需要手动全局安装它们：npm install -g markmap-cli @mermaid-js/mermaid-cli。