graphthulhu (Skridlevsky)

graphthulhu

MCP服务器，让AI完全访问您的知识图谱。支持 Logseq 和 黑曜石 --两者都具有完全的读写支持。浏览页面、搜索块、分析链接结构、跟踪决策、管理抽认卡和编写内容——所有这些都贯穿整个 模型上下文协议.

内置Go with 官方MCP Go SDK.

为什么

您的知识图存储相互连接的页面、块和链接。但是人工智能助手看不到任何东西——他们对你的第二个大脑视而不见。

graphthulhu解决了这个问题。它通过MCP公开您的整个知识图，因此Claude（或任何MCP客户端）可以：

• 读取任何具有完整块树、解析链接、标签和属性的页面
• 在所有具有上下文结果的区块中搜索（父链+兄弟链）
• 遍历链接图，发现概念是如何连接的
• 找出知识缺口——孤立页面、死角、弱链接区域
• 通过关联组件分析发现主题集群
• 创建页面、写入块、构建层次结构、双向链接页面（Logseq）
• 使用原始DataScript/Datalog查询内置工具未涵盖的任何内容（Logseq）
• 查看带有间隔重复统计的抽认卡（Logseq）
• 探索白板及其空间连接（Logseq）

它将“告诉我关于X”变成了一个真正理解你的知识图结构的人工智能。

工具

9个类别的37个工具。大多数工作都有两个后端；有些只是Logseq（DataScript查询、闪卡、白板）。

导航

搜索

分析

写

决定

期刊

抽认卡

白板

健康

安装

下载二进制文件

从以下网址获取您平台的最新版本 并将其添加到您的PATH中。

去安装

go install github.com/skridlevsky/graphthulhu@latest

从源代码构建

git clone https://github.com/skridlevsky/graphthulhu.git
cd graphthulhu
go build -o graphthulhu .

设置：Logseq

1. 在Logseq中，转到 设置→ 特性 并启用 HTTP API服务器
2. 点击 API 出现在顶部工具栏中的图标
3. 点击 启动服务器
4. 点击 创建令牌 并复制生成的令牌——您需要它进行配置

API运行于 http://127.0.0.1:12315 默认情况下。

设置：黑曜石

无需插件或服务器。graphthulhu读取你的保险库 .md 文件直接。

您需要提供vault的路径：

graphthulhu serve --backend obsidian --vault /path/to/your/vault

或者通过环境变量：

export GRAPHTHULHU_BACKEND=obsidian
export OBSIDIAN_VAULT_PATH=/path/to/your/vault
graphthulhu

黑曜石后端支持完整的读写操作。它将YAML frontmatter解析为属性，从标题和索引构建块树 [[wikilinks]] 用于反向链接解析。写入使用原子临时文件重命名，每次修改后都会重建内存中的索引。文件监视（fsnotify）使索引与外部编辑保持同步。从可配置的子文件夹中检测每日笔记（默认值： daily notes).

配置

Logseq——克劳德密码

添加到MCP设置(~/.claude/claude_code_config.json 或项目级别 .claude/settings.json):

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "env": {
        "LOGSEQ_API_URL": "http://127.0.0.1:12315",
        "LOGSEQ_API_TOKEN": "your-token-here"
      }
    }
  }
}

Logseq--克劳德桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "env": {
        "LOGSEQ_API_URL": "http://127.0.0.1:12315",
        "LOGSEQ_API_TOKEN": "your-token-here"
      }
    }
  }
}

黑曜石——克劳德密码

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "args": ["--backend", "obsidian", "--vault", "/path/to/your/vault"],
      "env": {}
    }
  }
}

黑曜石--克劳德桌面

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "args": ["--backend", "obsidian", "--vault", "/path/to/your/vault"],
      "env": {}
    }
  }
}

只读模式

要禁用所有写入操作（Logseq--Obsidian始终是只读的）：

{
  "mcpServers": {
    "graphthulhu": {
      "command": "graphthulhu",
      "args": ["--read-only"],
      "env": {
        "LOGSEQ_API_URL": "http://127.0.0.1:12315",
        "LOGSEQ_API_TOKEN": "your-token-here"
      }
    }
  }
}

版本控制警告

在使用Logseq后端启动时，graphthulhu会检查您的图目录是否受git控制。如果没有，它会向stderr打印一条警告，建议您初始化版本控制。没有它，写入操作无法撤消。

环境变量

建筑

main.go              Entry point — backend routing, MCP server startup
cli.go               CLI subcommands: journal, add, search
server.go            MCP server setup — conditional tool registration
backend/backend.go   Backend interface + optional capability interfaces
client/logseq.go     Logseq HTTP API client with retry/backoff
vault/
  vault.go           Obsidian vault client — reads .md files into Backend interface
  markdown.go        Markdown → block tree parser (heading-based sectioning)
  frontmatter.go     YAML frontmatter parser
  index.go           Backlink index builder from [[wikilinks]]
tools/
  navigate.go        Page, block, links, references, BFS traversal
  search.go          Full-text, property, DataScript/frontmatter, tag search
  analyze.go         Graph overview, connections, gaps, clusters
  write.go           Create, update, delete, move, link operations
  decision.go        Decision protocol: check, create, resolve, defer, analysis health
  journal.go         Date range and search within journals
  flashcard.go       SRS overview, due cards, card creation
  whiteboard.go      List and inspect whiteboards
  helpers.go         Result formatting utilities
graph/
  builder.go         In-memory graph construction from any backend
  algorithms.go      Overview, connections, gaps, clusters, BFS
parser/content.go    Regex extraction of [[links]], ((refs)), #tags, properties
types/
  logseq.go          Shared types with custom JSON unmarshaling
  tools.go           Input types for all 32 tools

设计决策

• 后端接口。 所有工具程序均针对 backend.Backend不是一个具体的客户。添加新的后端意味着实现接口——不需要更改工具。
• 完整的方块树，而不是平面文本。 每次读取页面都会返回完整的嵌套层次结构，每个块上都有解析的元数据。
• 每个搜索结果的上下文。 搜索不仅返回匹配的块，还包括父链和兄弟链，以便AI了解结果所在的位置。
• 用于分析的内存图。 分析工具在内存中构建BFS、连接组件和间隙检测的完整链接图。这使得每次查询的延迟保持较低水平。
• 可选功能接口。 工具如 query_properties 和 find_by_tag 检查后端是否实现 PropertySearcher 或 TagSearcher 在运行时，回到DataScript for Logseq。这允许Obsidian使用文件扫描，而Logseq保留其Datalog查询。
• DataScript作为逃生口。 当内置工具不覆盖查询时， query_datalog 允许您对Logseq数据库运行任意Datalog。
• 对每个块进行内容解析。 解析器提取 [[links]], ((block refs)), #tags, key:: value 原始块内容中的属性、任务标记和优先级。
• 黑曜石的标题块。 黑曜石标记按标题（H1-H6）划分为层次块树。块UUID通过以下方式持久化 `` HTML注释用于跨编辑的稳定性，对于没有嵌入ID的文件，具有确定性回退。
• 文件监视。 黑曜石后端使用fsnotify监视vault目录，并有选择地重新索引更改的文件，使内存中的索引与外部编辑保持同步。

发展

go build -o graphthulhu .          # Build
go test ./...                       # Test
go vet ./...                        # Vet

许可证

麻省理工学院