zk-mcp: Instructions file for Claude Code

CLAUDE.md

プロジェクト概要

これはzkプレーンテキストノート取りシステムと統合するMCP（Model Context Protocol）サーバーです。このサーバーはLLMがzkで管理されたナレッジベースにアクセスしクエリを実行するためのツールを提供します。

主要コマンド

開発

• make run - ZK_DIR=.でMCPサーバーを開発モードで実行
• make format - ruffを使用してコードをフォーマット（インポート + フォーマット）
• make lint - ruffでリント、mypyで型チェックを実行
• make test - テストを実行（開発依存関係のpytestを使用）
• make pre-commit - formatとlintの両方を実行（コミット前推奨）

パッケージ管理

• uv add <package> - ランタイム依存関係を追加
• uv add --dev <package> - 開発依存関係を追加
• uv run <command> - 仮想環境でコマンドを実行

アーキテクチャ

コアコンポーネント

1. server.py - FastMCPを使用したメインのMCPサーバー実装

   • 5つのMCPツールを定義: get_note_paths, get_linking_notes, get_tags, get_note, create_note
   • zk CLIとのやり取りにsubprocessを使用
   • 全ツールはPydanticモデルを使用してJSONレスポンスを返す

2. tools/ - 各MCPツールの実装

   • get_note_paths.py - 複雑なフィルタリングでノートをクエリ
   • get_linking_notes.py - ノートのリンク関係を分析
   • get_tags.py - 利用可能なタグをリスト
   • get_note.py - 特定のノートの内容を読み取り
   • create_note.py - 新しいノートを作成
   • models.py - APIレスポンス用のPydanticデータモデル

3. settings.py - pydantic-settingsを使用した設定

   • zk_dir - zkノートディレクトリへのパス（ZK_DIR環境変数で設定）

MCPツール

get_note_paths()

複雑なフィルタリングでノートをクエリ：

• include_str - コンテンツまたはファイル名に含まれる文字列でフィルタ
• include_str_operand - 複数の文字列フィルタの論理演算子（AND/OR）
• exclude_str - 特定の文字列を含むノートを除外
• include_tags - タグでフィルタ
• include_tags_operand - 複数のタグフィルタの論理演算子（AND/OR）
• exclude_tags - 特定のタグを持つノートを除外

get_linking_notes(path)

特定のノートのリンク関係を分析：

• link_to_notes - 指定されたノートがリンクしているノート
• linked_by_notes - 指定されたノートにリンクしているノート
• related_notes - 指定されたノートと関連するノート

get_tags()

ノートブック内の利用可能なタグをすべてリスト

get_note(path)

特定のノートの完全なコンテンツを読み取り

create_note(title, directory)

新しいノートを作成（オプションでディレクトリを指定）

依存関係

• ランタイム: mcp[cli]>=1.6.0, pydantic-settings>=2.8.1
• 開発: mypy>=1.15.0, pytest>=8.3.5, ruff>=0.11.5

構成

サーバーには以下が必要：

1. zk CLIツールがインストールされPATHに含まれていること
2. zkノートディレクトリを指すZK_DIR環境変数
3. MCPクライアント設定（servers.json設定についてはREADME.mdを参照）

MCPクライアント設定例

{
  "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/"
      }
    }
  }
}