Skip to main content
Glama
jamesfishwick

Slipbox MCP Server

Slipbox MCP 服务器

Slipbox

让你的 AI 助手在知识管理中扮演主动角色。Slipbox 是一个 MCP 服务器,能将任何兼容 MCP 的代理变成你的 Zettelkasten 伙伴——创建原子笔记、形成语义链接、发现涌现的聚类,并从你现有的知识中综合出洞见。

你的想法输入,结构化知识输出。代理负责格式化、链接和整合。

不熟悉这种方法?从 Zettelkasten 方法简介 开始,了解原子笔记和链接式思考背后的原理。想了解 Slipbox 如何用这种方法武装你的代理,请阅读它在连接时自动附带的服务器指令

使用 Claude 构建和测试。适用于任何 MCP 客户端(Claude Desktop、Claude Code、OpenCode、Copilot,或任何支持 MCP 的工具)。

纯文件,零锁定。 笔记是带 YAML frontmatter 的 markdown——可在 Obsidian、Foam、Logseq 或任何编辑器中阅读。SQLite 数据库只是一个索引,不是事实来源。随时删除它并从文件重建。

  • 19 个 MCP 工具,用于笔记、链接、搜索、图分析和聚类管理

  • 6 个工作流提示(以及配套技能),编码了 Zettelkasten 方法,让你不必每次会话都重新学习

  • BM25 全文搜索,通过 SQLite FTS5 搜索标题和内容

  • 聚类检测,发现涌现的主题分组并搭建结构笔记

  • 七种类型化链接(引用、扩展、细化、反驳、质疑、支持、相关)

Python 3.10+ | macOS 或 Linux

直接捕捉想法:你的原始思考输入,带标签和链接的格式化原子笔记输出

演示

观看 Slipbox 演示

Related MCP server: vault-master-mcp

快速开始

1. 安装

pipx install slipbox-mcp
# or, with uv:
uv tool install slipbox-mcp

这会将 slipbox-mcp 启动器放到你的 PATH 中(位于 ~/.local/bin)。这一个命令就是整个 MCP 服务器:无需克隆、无需 PYTHONPATH、无需硬编码的 venv Python 路径。下面所有内容都使用它。如果完全不想安装就想试用,uvx slipbox-mcp 会在一个临时环境中运行服务器。

(正在开发 Slipbox 本身?参见开发了解克隆 + 可编辑安装的设置。)

2. 选择数据目录

一个变量 SLIPBOX_BASE_DIR 配置一切:笔记存放在 <base>/data/notes,SQLite 索引在 <base>/data/db/zettelkasten.db。服务器在首次运行时创建这些目录,权限为仅所有者(0700)。

SLIPBOX_BASE_DIR(或下面单独的 SLIPBOX_NOTES_DIR / SLIPBOX_DATABASE_PATH 路径)指向你控制的专用数据目录,而不是共享或系统位置。这些路径按原样使用:服务器在其下管理笔记树和索引,并在重建索引时将笔记目录视为事实来源。

# Example: use any absolute path you like
/Users/yourname/.local/share/mcp/slipbox

使用完整的绝对路径。开头的 ~ 不会在 MCP 客户端配置文件中展开,会创建一个字面的 ~ 目录。

3. 连接到你的 MCP 客户端

Claude Code(一条命令,无需编辑文件):

claude mcp add slipbox \
  --env SLIPBOX_BASE_DIR=/Users/yourname/.local/share/mcp/slipbox \
  -- slipbox-mcp

Claude Desktop(编辑配置文件):

  • macOS~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "slipbox": {
      "command": "slipbox-mcp",
      "env": {
        "SLIPBOX_BASE_DIR": "/Users/yourname/.local/share/mcp/slipbox"
      }
    }
  }
}

Desktop PATH 注意事项: macOS 桌面应用并不总是继承 ~/.local/bin 到其 PATH 中,因此裸的 "slipbox-mcp" 可能无法解析。如果服务器启动失败,请将 "command": "slipbox-mcp" 替换为 which slipbox-mcp 打印的绝对路径(通常是 /Users/yourname/.local/bin/slipbox-mcp)。

其他 MCP 客户端:slipbox-mcp 注册为服务器命令,并在其环境中设置 SLIPBOX_BASE_DIR。命令和环境变量在所有地方都是一样的。

不用 SLIPBOX_BASE_DIR,而是单独设置绝对路径。可选的 SLIPBOX_LOG_LEVEL 取值为 DEBUGINFOWARNINGERROR 之一。

"env": {
  "SLIPBOX_NOTES_DIR": "/Users/yourname/.local/share/mcp/slipbox/notes",
  "SLIPBOX_DATABASE_PATH": "/Users/yourname/.local/share/mcp/slipbox/data/db/zettelkasten.db",
  "SLIPBOX_LOG_LEVEL": "INFO"
}

4. 重启并验证

重启你的客户端(Claude Code 在下次启动时重新加载;退出并重新打开 Claude Desktop)。

向你的代理提问:

  • "创建一条关于某事的测试笔记"

  • "在我的 slipbox 中搜索 test"

  • "查找孤立笔记"


实际效果

上面的主图是核心循环。以下是代理还能做的其他事情。

主动维护

代理在会话开始时读取 slipbox://maintenance-status 资源,并呈现需要整理的聚类。

主动维护

全文搜索

通过 slipbox_search_notes 对笔记进行 BM25 排序搜索。

FTS5 搜索

知识图谱:中心笔记

slipbox_find_central_notes 呈现图的结构锚点——所有其他笔记围绕其运转的笔记。

中心笔记

笔记分析

analyze_note 提示评估原子性,在现有图中找到真实连接,建议标签,并重写以提高清晰度。

笔记分析

来源分解

knowledge_creation 提示将一篇文章拆分为带正确引用和链接的原子文献笔记。

来源分解

聚类检测

slipbox_get_cluster_report 查找缺乏结构笔记的共现标签组。按规模、孤立比例、链接密度和时效性评分。

聚类报告

结构笔记创建

slipbox_create_structure_from_cluster 搭建结构笔记,链接所有成员笔记,并关闭该聚类。

结构笔记

孤立笔记

slipbox_find_orphaned_notes 呈现未整合的知识——适合连接或删除的候选。

孤立笔记

相似笔记

slipbox_find_similar_notes 根据共享标签、共同链接和内容重叠计算相似度。

相似笔记

图遍历

slipbox_get_linked_notes 显示从枢纽笔记出发的类型化链接,按链接类型分组。

链接笔记

知识综合

knowledge_synthesis 提示在未连接的区域之间寻找桥梁,并从你现有的知识中提出综合笔记。

知识综合

零锁定:Obsidian 中的纯文件

笔记是纯 markdown。在 Obsidian 中打开 vault,一切都能正常工作——渲染内容、反向链接和知识图谱。

如果想要一个以彩色渲染类型化链接(支持、扩展、细化……)而非 Obsidian 内置无类型图的图谱,请安装配套插件 Slipbox Semantic Graph——一个力导向视图,带有人性化标题和颜色编码的语义链接类型。从 0.1.0 版本手动安装:将 main.jsmanifest.jsonstyles.css 复制到 <vault>/.obsidian/plugins/slipbox-graph/,然后在 设置 → 社区插件 中启用。(一旦被官方目录收录,你也可以通过 设置 → 社区插件 → 浏览 → 搜索 "Slipbox Semantic Graph" 来安装。)它读取服务器写入的相同 frontmatter id## Links 部分,因此无需额外配置。使用 打开语义图 命令(命令面板)或 git-fork 功能区图标打开视图。

Slipbox Semantic Graph:整个 vault,类型化链接按关系进行颜色编码

顶部的图例将每种颜色映射到一种链接类型(扩展、细化、支持、反驳、质疑、相关)。聚焦一个结构笔记,它的星座图就会呈现出来。这里是 Contract Testing Knowledge Map 及其环绕的成员笔记:

Slipbox Semantic Graph:一个结构笔记及其成员笔记星座图


可选:自动聚类检测

聚类分析扫描所有笔记并计算相似度分数。每天运行(早上 6 点)会预计算结果,使 slipbox_get_cluster_report() 即时返回。如果不安排计划,聚类检测按需运行,对于大型集合来说会较慢。

在批量导入、重大重组之后,或当你想要立即获得结果时,手动运行。

安装聚类检测(macOS)

chmod +x scripts/install-cluster-detection.sh
./scripts/install-cluster-detection.sh

安装程序会检测你的 Python/venv 路径,生成 LaunchAgent plist,并加载它。

手动测试(文件监视器)

source .venv/bin/activate
python scripts/detect_clusters.py

输出保存到 ~/.local/share/mcp/slipbox/cluster-analysis.json

卸载聚类检测

./scripts/install-cluster-detection.sh --uninstall

可选:用于自动索引的 macOS 文件监视器

MCP 服务器维护一个数据库索引以支持快速搜索。在 Obsidian(或任何编辑器)中编辑笔记会使数据库过期,直到你运行 slipbox_rebuild_index

文件监视器作为后台守护进程运行,监视你的笔记目录,并在 .md 文件发生变化时自动重建索引。

如果你经常在 Obsidian 中编辑笔记,同时也在使用 Claude,请使用它。

安装文件监视器(macOS)

chmod +x scripts/install-file-watcher.sh
./scripts/install-file-watcher.sh

安装程序会检测你的 Python/venv 路径,在需要时安装 watchdog,并加载 LaunchAgent。登录时启动,崩溃时自动重启。

手动测试

source .venv/bin/activate
python scripts/watch_notes.py

编辑一个笔记文件。你应该会在监视器输出中看到 "rebuilding index..."。

检查状态

launchctl list | grep slipbox.watcher

# View logs

tail -f ~/.local/share/mcp/slipbox/watcher.log

卸载文件监视器

./scripts/install-file-watcher.sh --uninstall

推荐系统提示

Slipbox 自动附带一个基线:每个客户端在连接时都会收到服务器指令,涵盖如何用好这些工具——笔记类型、链接语义、质量标准,以及搜索-先于-创建等核心工作流。你不需要自己添加这些。

docs/SYSTEM_PROMPT.md可选加入的叠加层:服务器不应自行断言的自主性和主动性指令。将其添加到你的代理偏好或系统提示中,以启用:

  • 对话期间的自动知识捕获

  • 对话开始时的聚类涌现检测


工具参考

核心笔记操作

工具

描述

slipbox_create_note

创建原子笔记(fleeting/literature/permanent/structure/hub)

slipbox_get_note

按 ID 或标题检索笔记

slipbox_update_note

更新现有笔记

slipbox_delete_note

删除笔记

链接

工具

描述

slipbox_create_link

在笔记之间创建语义链接

slipbox_remove_link

移除链接

slipbox_delete_link

删除特定链接(如果链接不存在则报错)

slipbox_get_linked_notes

获取链接到/自某笔记的笔记

搜索与发现

工具

描述

slipbox_search_notes

按文本(BM25 排序)、标签或类型搜索

slipbox_find_similar_notes

查找与给定笔记相似的笔记

slipbox_find_central_notes

查找连接最多的笔记

slipbox_find_orphaned_notes

查找未连接的笔记

slipbox_list_notes_by_date

按日期范围列出笔记

slipbox_get_all_tags

列出所有标签

聚类分析

工具

描述

slipbox_get_cluster_report

获取待处理的需要结构笔记的聚类

slipbox_create_structure_from_cluster

从聚类创建结构笔记

slipbox_refresh_clusters

重新生成聚类分析

slipbox_dismiss_cluster

从建议中永久忽略某个聚类

维护

工具

描述

slipbox_rebuild_index

从文件重建数据库索引


提示词参考

MCP 提示词是可复用的工作流模板,它们将 Zettelkasten 方法编码其中,这样你就不必在每次会话中重新解释它。

提示词

描述

使用场景

knowledge_creation

将信息处理为 3-5 条原子笔记

添加文章、想法或笔记

knowledge_creation_batch

将较大体量处理为 5-10 条笔记

处理书籍或长篇内容

knowledge_exploration

映射与现有知识的连接

探索主题之间的关联

knowledge_synthesis

创建更高层次的洞见

在想法之间寻找桥梁

analyze_note

评估笔记是否适合放入 slipbox

审阅新笔记或现有笔记

cluster_maintenance

呈现待处理的后台维护事项

工作会话开始时

如何调用:斜杠命令与技能

每个工作流都有两种提供方式:

  • MCP 提示词:由运行中的服务器提供。

  • 技能:独立捆绑包(skills/<name>/),运行相同的工作流并增加自然语言触发。

六个技能中有五个是从服务器使用的同一 PROMPT_* 模板生成的(src/slipbox_mcp/server/descriptions.py),如果提交的 skills/ 与这些模板发生偏差,CI 会失败。第六个 cluster-maintenance 直接在 scripts/build_skills.py 中编写,因为它的 MCP 提示词是运行时渲染的状态消息,而不是可复用的工作流。

斜杠命令是可靠的路径。Claude Code 将 MCP 提示词显示为 /mcp__<server>__<prompt>;输入 /mcp__slipbox-mcp__ 即可打开选择器:

/mcp__slipbox-mcp__knowledge_creation
/mcp__slipbox-mcp__knowledge_exploration
/mcp__slipbox-mcp__knowledge_synthesis
/mcp__slipbox-mcp__knowledge_creation_batch
/mcp__slipbox-mcp__analyze_note
/mcp__slipbox-mcp__cluster_maintenance

(已安装的技能也会按目录名暴露自己的斜杠命令,例如 /slipbox-analyze-note。)

自然语言在安装了匹配的技能后即可使用。只需描述你想要的内容:

Analyze this note for my slipbox: [paste note]

Add this to my slipbox: [paste article]

Synthesize my notes on attention and memory.

散文式触发取决于技能是否已安装以及你的措辞是否与其描述匹配;如果未触发,请回退到斜杠命令。要求模型按名称"使用 analyze_note 提示词"是起作用的。模型无法按名称调用 MCP 提示词。请使用斜杠命令,或让技能从自然语言中触发。

安装技能

Claude Code.claude/skills/(按项目)或 ~/.claude/skills/(全局)发现技能,而不是从顶层的 skills/ 目录。将你想要的技能符号链接或复制到发现路径中(例如,对于此项目):

mkdir -p .claude/skills
ln -s ../../skills/slipbox-analyze-note .claude/skills/slipbox-analyze-note
# ...or copy the directories, or symlink all six

Claude Desktop 需要将每个技能作为 .skill 捆绑包。先构建它们,然后上传:

python scripts/build_skills.py     # writes dist/*.skill

转到 设置 → 技能 → 上传技能,然后选择你想要的 dist/ 中的捆绑包。每个技能都会同时安装为斜杠命令和自然语言触发器。

descriptions.py 中编辑提示词模板后,重新运行构建以重新生成技能。


链接类型

类型

使用场景

反向链接

reference

通用的"另见"连接

reference

extends

在另一个想法的基础上进行扩展

extended_by

refines

澄清或改进

refined_by

contradicts

相反的观点

contradicted_by

questions

对某事提出疑问

questioned_by

supports

为某事提供证据

supported_by

related

松散的主题关联

related


笔记类型

类型

用途

fleeting

快速捕捉,未处理的想法

literature

来自来源的想法,附有引用

permanent

用你自己的话表达的提炼后的想法

structure

组织特定主题下 7-15 条相关笔记的地图

hub

链接到结构笔记的领域概览;浏览广泛知识领域的入口点

结构笔记与枢纽笔记: 结构笔记围绕单一主题组织一组永久笔记。它是位于笔记本身之上一个层级的精选地图。枢纽笔记则再高一个层级:它链接到整个知识领域中的结构笔记(偶尔也链接到关键永久笔记)。结构笔记回答"我对 X 了解什么?",而枢纽笔记回答"我对整个领域的知识是如何组织的?"大多数 Zettelkasten 只需要少量枢纽笔记。


文件格式

笔记以带 YAML frontmatter 的 Markdown 文件存储:

---
id: "20251217T172432480464000"
title: "Poetry Revision Principles"
type: structure
tags:
  - poetry
  - revision
  - craft
created: "2025-12-17T17:24:32"
updated: "2025-12-17T17:24:32"
---

# Poetry Revision Principles

Content here...

## Links

- reference [[20250728T125429845760000]] Member of structure

你可以直接在任意文本编辑器或 Obsidian 中编辑这些文件。在外部编辑后运行 slipbox_rebuild_index


升级

拉取新版本后,重启 Claude Desktop。如果发布说明提到数据库变更,请运行一次 slipbox_rebuild_index 以将现有数据库更新到最新状态。

升级到 FTS5 搜索(FTS5 发布之后的任何版本): 全文搜索索引会在服务器针对新数据库启动时自动创建。对于现有数据库,FTS5 表会在首次启动时创建,但会一直为空,直到你运行:

slipbox_rebuild_index

这会从现有笔记填充 BM25 索引。在此之前,搜索结果不会按相关性排序。


故障排除

服务器未在 Claude Desktop 中加载

  1. 确认启动器可解析:which slipbox-mcp 应打印一个路径(通常是 ~/.local/bin/slipbox-mcp)。

  2. 如果它在你的终端中可解析,但 Desktop 仍然无法启动它,说明 GUI 应用在其 PATH 中看不到 ~/.local/bin。将 "command": "slipbox-mcp" 替换为步骤 1 中的绝对路径。

  3. 检查 Claude Desktop 日志中的错误。

slipbox-mcp: command not found

控制台脚本未安装或不在 PATH 中。使用 pipx install --editable . --force 重新安装,然后用 which slipbox-mcp 验证。如果 pipx 的 bin 目录不在 PATH 中,运行 pipx ensurepath 并重启你的 shell。

笔记目录指向字面上的 ~/...

如果你的笔记目录最终位于相对于 CWD 的 ./~/...,说明你在 JSON 配置中使用了 ~。Claude Desktop 不会展开 ~。请将其替换为完整的绝对路径。

搜索返回无结果

  1. FTS5 索引可能尚未填充。运行一次 slipbox_rebuild_index 以索引现有笔记。

  2. 如果你最近在 Claude 之外编辑了笔记,索引可能已过期。运行 slipbox_rebuild_index

slipbox_list_notes_by_date 返回空结果

如果 start_date 晚于 end_date,则没有笔记匹配,返回空结果。这是预期行为,不是错误。

数据库不同步

如果笔记是在 MCP 服务器之外编辑的:

slipbox_rebuild_index

聚类检测未运行

launchctl list | grep slipbox.cluster-detection
# Should show: - 0 com.slipbox.cluster-detection

# Check logs

cat /tmp/slipbox-clusters.log

# Reinstall if needed

./scripts/install-cluster-detection.sh --uninstall
./scripts/install-cluster-detection.sh

文件监视器未运行

launchctl list | grep slipbox.watcher
# Should show: - 0 com.slipbox.watcher

# Check logs

cat ~/.local/share/mcp/slipbox/watcher.log

# Reinstall if needed

./scripts/install-file-watcher.sh --uninstall
./scripts/install-file-watcher.sh

ZETTELKASTEN_* 环境变量升级

如果你之前使用过 ZETTELKASTEN_NOTES_DIRZETTELKASTEN_DATABASE_PATH 或其他 ZETTELKASTEN_* 变量,它们不再被读取。请将它们重命名为对应的 SLIPBOX_* 变量:

旧变量

新变量

ZETTELKASTEN_NOTES_DIR

SLIPBOX_NOTES_DIR

ZETTELKASTEN_DATABASE_PATH

SLIPBOX_DATABASE_PATH

ZETTELKASTEN_LOG_LEVEL

SLIPBOX_LOG_LEVEL

ZETTELKASTEN_BASE_DIR

SLIPBOX_BASE_DIR

ZETTELKASTEN_SERVER_NAME

SLIPBOX_SERVER_NAME

如果检测到旧名称,服务器会记录一条警告,但不会自动迁移它们。

聚类报告路径不可配置

聚类分析报告始终写入 ~/.local/share/mcp/slipbox/cluster-analysis.json,无论 SLIPBOX_BASE_DIRSLIPBOX_NOTES_DIR 如何设置。如果你使用非默认路径,聚类报告仍会位于默认位置。

安装脚本仅适用于 macOS

scripts/install-cluster-detection.shscripts/install-file-watcher.sh 脚本使用 launchctl~/Library/LaunchAgents/,这些仅存在于 macOS 上。在 Linux 上,你需要手动创建等效的 systemd 单元或 cron 作业。请参阅相关 README 章节中的手动测试命令,以验证底层 Python 脚本在你的平台上是否正常工作。

默认路径相对于工作目录

如果未设置 SLIPBOX_NOTES_DIRSLIPBOX_DATABASE_PATH,服务器默认使用 data/notesdata/db/zettelkasten.db相对于当前工作目录。通过 Claude Desktop 运行时,CWD 可能不是你预期的目录。始终在 claude_desktop_config.json 中设置绝对路径以避免此问题。


开发

设置

git clone https://github.com/jamesfishwick/slipbox-mcp.git
cd slipbox-mcp
uv venv && uv pip install -e ".[dev]"

测试

项目有三层测试:

层级

数量

速度

成本

命令

单元 + 集成测试

219

~2s

免费

pytest tests/

工具契约测试

22

~0.5s

免费

pytest evals/tool_contracts/

LLM 评估

28

~10分钟

~$3-5

pytest evals/llm/

# Default: runs unit + contract tests (CI runs this)

pytest

# Run everything except LLM evals

pytest tests/ evals/tool_contracts/

# Run LLM evals (requires claude CLI authenticated)

pytest evals/llm/ -v

# Run LLM evals with a specific model

EVAL_MODEL=sonnet pytest evals/llm/ -v

# Lint

ruff check src/ evals/

单元测试覆盖内部逻辑——服务、仓库、模型、解析。

工具契约测试验证 LLM 所看到的 MCP 工具输出格式——可解析的结构、链式调用(创建 -> 搜索 -> 获取)以及有用的错误消息。这些测试是确定性的,不调用任何 LLM。

LLM 评估通过 claude CLI 在连接 MCP 服务器的情况下向 LLM 发送提示词,然后通过检查数据库状态(创建的笔记、建立的链接、应用的标签)来评分结果。它们测试 LLM 在给定工具描述的情况下是否实际正确使用工具。

CI/CD

分支保护: 直接推送到 main 被阻止。所有更改都通过 PR 进行。

工作流

触发器

运行器

说明

CI

每个 PR + 推送到 main

GitHub 托管

单元测试 + 契约测试,ruff 检查 + 格式化

LLM Evals

选择加入(标签或手动)

自托管

通过 claude CLI 运行 28 个 LLM 评估

Release

推送到 main

GitHub 托管

release-please PR;合并后构建并发布到 PyPI

LLM 评估套件成本较高(约 3-5 美元,约 10 分钟)且为自托管,因此它绝不会自动运行。基于路径的触发器无法区分真正的提示词变更与表面性的重新格式化。当你更改提示词或工具描述语义时,请刻意运行它:

  • 为 PR 添加 run-llm-evals 标签。它会运行,并且在标签存在期间每次推送都会重新运行。

  • 或者从 Actions 标签页手动触发workflow_dispatch)。

  • 或者在没有 runner 的情况下本地运行pytest evals/llm/ -v

没有标签或手动触发时,该任务会被跳过(不分配 runner,不产生成本)。

自定义评估设置

如果你不想要自托管 runner: 删除 .github/workflows/llm-evals.yml,并在合并提示词更改前在本地运行 pytest evals/llm/ -v

如果你希望每个 PR 都自动运行 LLM 评估: 添加带有相关 paths: 过滤器的 pull_request 触发器,并移除任务 if: 中的标签门控。但要注意仅格式化编辑也会意外触发。

要更改默认评估模型: 在你的环境或工作流文件中设置 EVAL_MODEL。默认为 haiku,以兼顾速度/成本。

要设置自托管 runner:

# Get a registration token

gh api repos/OWNER/REPO/actions/runners/registration-token -X POST -q '.token'

# Download and configure

mkdir -p ~/.github-runners/slipbox-mcp && cd ~/.github-runners/slipbox-mcp
curl -sL -o actions-runner.tar.gz https://github.com/actions/runner/releases/latest/download/actions-runner-osx-arm64-2.325.0.tar.gz
tar xzf actions-runner.tar.gz
./config.sh --url https://github.com/OWNER/REPO --token <TOKEN> --unattended
nohup ./run.sh &

发布到 PyPI

发布是自动化的。Release 工作流(.github/workflows/release.yml)在每次推送到 main 时运行 release-please,并通过 PyPI 可信发布(OIDC,因此仓库机密中不存储 API 令牌)进行发布。

流程(你永远不需要手动编辑版本号或推送标签):

  1. 使用 Conventional Commit 消息将更改合入 mainfeat: → 次版本号提升,fix: → 补丁版本提升,feat!:/BREAKING CHANGE: → 主版本号提升)。仓库的提交钩子已经强制了这种格式。

  2. release-please 会保持一个常开的 "release PR",累积下一次版本号提升(在 src/slipbox_mcp/__init__.py 中)以及从这些提交派生的 CHANGELOG.md 条目。

  3. 当你准备好发布时,合并 release PR。 这会为发布打标签(v<version>),并在同一次工作流运行中构建 sdist + wheel,运行 twine check,并发布到 PyPI。

因此发布只需一次点击:合并机器人的 PR。仅此而已。

提交类型决定版本号。因此请准确输入类型。 版本号提升是根据自上次发布以来的 Conventional Commit 前缀机械计算的,而不是根据更改的大小。将 feat:/fix: 保留给已发布包的更改;其他一切使用非发布类型:

前缀

版本影响

用途

feat:

次版本(1.3.0 → 1.4.0)

包中的新运行时能力

fix:

补丁(1.3.0 → 1.3.1)

包中的错误修复

feat!: / BREAKING CHANGE:

主版本(1.3.0 → 2.0.0)

不向后兼容的更改

docs: ci: build: chore: test: refactor:

文档、工具、CI、打包、仅内部更改

一批仅包含非发布提交的更改根本不会产生 release PR。squash-merge 的标题就是 release-please 读取的提交,因此 PR 标题的前缀才是关键。请根据获得了什么来标注,而不是根据投入的工作量。

一次性设置(此仓库已完成,为 fork 记录):

  1. 在 PyPI 上,为项目 slipbox-mcp 注册一个待定可信发布者Owner: jamesfishwick · Repository: slipbox-mcp · Workflow: release.yml · Environment: release。四项必须完全匹配。

  2. 在 GitHub 中,创建一个名为 release 的环境(Settings → Environments)。如果你限制其部署引用,请添加一个标签规则 v*(同名的分支规则不会匹配该标签)。

版本号只定义一次,在 src/slipbox_mcp/__init__.py 中(release-please 会提升它;# x-release-please-version 标记告诉它哪一行)。pyproject.tomldynamic = ["version"])和服务器的 server_version 都从它读取,因此无需保持同步;release-please 打出的标签在构造上始终与包版本匹配。

要预演构建而不发布,请手动运行:python -m build && twine check dist/*(并使用 TestPyPI 令牌运行 twine upload --repository testpypi dist/* 来试运行上传)。

共享提示词常量

所有工具描述和提示词模板都位于 src/slipbox_mcp/server/descriptions.py 中。MCP 服务器和评估测试都从这个单一事实来源导入。如果你更改了提示词,评估会测试 LLM 是否仍能使用新措辞正确运行。

调试日志

SLIPBOX_LOG_LEVEL=DEBUG python -c "from slipbox_mcp.main import main; main()"

CLI 工具

slipbox 命令为机械性操作提供终端访问:

slipbox status          # Overview of notes, tags, orphans, pending clusters
slipbox search <query>  # Find notes by text
slipbox clusters        # Show pending structure note candidates
slipbox orphans         # List unconnected notes
slipbox rebuild         # Rebuild index (add --clusters to refresh cluster analysis)
slipbox export <id>     # Export note markdown to stdout
slipbox tags            # List all tags with usage counts

安装:pipx install --editable .(将 slipbox 添加到你的 PATH)


实验性:Slipbox 作为代理记忆

一个未经测试的假设,不是推荐的设置。以上所有内容帮助代理管理你的知识。这将其反转:代理使用 slipbox 作为其跨会话的持久记忆,取代原生记忆或规则文件。

模型在会话之间没有记忆,因此 slipbox 是一个会话留给下一个会话的唯一渠道。它为冷启动的继任者撰写简报(一次失败及其原因、一个反复出现的约束、一次纠正、一个来之不易的事实),将它们标记为 agent-memory,并在行动前搜索该标签。赌注是关联的记忆胜过扁平的规则文件,因为你可以通过遍历来检索它。

首先需要知道三件事:命名空间隔离是一种标签约定,而非强制性的,因此请针对单独的 slipbox 实例运行;"memory" 是一个误称,因为除了笔记本身之外没有什么是持久的;增长纪律是未经证实的部分,因此第一次运行时预计会出现蔓延。完整说明和注意事项:Slipbox as Agent Self-Memory

文档

文档

内容

Quick Reference

笔记 ID 格式、五种笔记类型,以及该方法的一页速查表。

Manual Zettelkasten Guide

在 Obsidian 中手动运行相同的工作流,不涉及代理。

Link Format

Slipbox 的链接如何映射到 [[wikilinks]] 和其他编辑器的格式。

Ecosystem Compatibility

哪些其他工具可以读写同一个 vault。

System Prompt

可选加入的自主层:自动捕获、聚类检测和代理记忆实验。

Demo

一个展示工具实际使用的完整会话。

贡献

参见 CONTRIBUTING.md 了解设置说明、编码标准以及如何提交更改。

路线图

参见 ROADMAP.md 了解计划的功能和未来方向。

赞助

如果 slipbox-mcp 对你有用,请考虑赞助该项目

许可证

MIT

Install Server
A
license - permissive license
A
quality
A
maintenance

Maintenance

Maintainers
<1hResponse time
3wRelease cycle
4Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • A
    license
    C
    quality
    F
    maintenance
    An MCP server that integrates the zk note-taking system with LLMs, enabling users to search, read, create, and manage notes. It provides tools for link analysis, tag management, and complex note queries to interact with local knowledge bases.
    5
    1
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that treats Obsidian vaults as knowledge graphs, enabling AI agents to traverse wikilinks, assemble token-budgeted context, and search with backlink awareness.
    3
    1
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    A local-first MCP server that gives AI assistants long-term memory by storing, searching, and recalling notes as Markdown files on your machine.
    15
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    A lightweight MCP server that enables AI assistants to securely read, create, and modify notes in an Obsidian vault, with support for semantic search and web scraping.
    2,472
    MIT

View all related MCP servers

Related MCP Connectors

  • Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.

  • Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer

  • Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jamesfishwick/slipbox-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server