zk MCP

zk-mcp

zk-mcp是一个mcp（模型上下文协议）服务器，用于集成由 zk LLMs。 它使LLM能够高效地访问zk下管理的知识库并与之交互。

特性

• 备注查询：按内容、标签和复杂过滤器搜索笔记
• 链接分析：发现笔记之间的关系（链接到、链接者、相关）
• 标签管理：按可用标签列出和筛选
• 注意访问：阅读完整的笔记内容
• 笔记创建：以编程方式创建新笔记

先决条件

• zk：一个纯文本笔记助手
• 紫外线
• 任何MCP客户端（例如，Claude Desktop、Continue等）

安装

1. 克隆此存储库：

git clone https://github.com/koei-kaji/zk-mcp.git
cd zk-mcp

1. 安装依赖项：

uv sync

配置

将以下设置添加到MCP客户端 servers.json:

{
  "mcpServers": {
    "zk": {
      "alwaysAllow": [
        "get_note",
        "get_note_paths",
        "get_linking_notes",
        "get_tags",
        "create_note"
      ],
      "args": [
        "--directory",
        "/path/to/zk-mcp/",
        "run",
        "server.py"
      ],
      "command": "uv",
      "env": {
        "ZK_DIR": "/path/to/your/zk-note-directory/"
      }
    }
  }
}

重要：替换 /path/to/zk-mcp/ 具有此存储库的实际路径，以及 /path/to/your/zk-note-directory/ 带有zknotes目录的路径。

可用的MCP工具

此服务器提供以下MCP工具：

get_note_paths

根据各种条件搜索笔记：

• include_str：过滤内容或文件名中包含特定字符串的注释
• 包括str_operatand：逻辑运算符(AND/OR)用于多个字符串过滤器
• exclude_str：排除包含特定字符串的注释
• include_tags：按标签过滤笔记
• include_tags_operand：逻辑运算符(AND/OR)用于多个标签过滤器
• exclude_tags：排除带有特定标签的注释

get_linking_notes

发现笔记关系：

• link_to_tonotes：注意指定的注释链接到
• linked_by_notes：指向指定注释的注释
• 相关注释：与指定注释相关的注释

get_tags

列出笔记存储库中的所有可用标签。

get_note

按路径阅读特定笔记的完整内容。

create_note

在可选目录中创建具有指定标题的新笔记。

发展

命令

• make run -在开发模式下运行MCP服务器 ZK_DIR=.
• make format -使用ruff格式化代码（导入+格式化）
• make lint -用褶边运行linting并用mypy进行类型检查
• make test -使用pytest运行所有测试
• make pre-commit -运行format和lint（建议在提交之前）

包管理

• `uv add

` -添加运行时依赖关系

• `uv add --dev

` -添加开发依赖关系

• uv run -在虚拟环境中运行命令

建筑

服务器是使用以下方式构建的：

• FastMCP：MCP服务器实现
• 派丹蒂克：数据验证和序列化
• zk命令行界面：后端与zk note系统集成

所有工具都使用Pydantic模型返回JSON响应，用于类型安全和验证。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。