kioq

Markdown ノートを WikiLink で構造化する MCP サーバ。日本語ファーストで、ローカルと GitHub の両方に対応。

クイックスタート

ローカル

npx @tomingtoming/kioq --root /path/to/notes

空ディレクトリでも開始できる。

GitHub

git clone [email protected]:you/notes.git ~/notes

KIOQ_GITHUB_TOKEN=ghp_... npx @tomingtoming/kioq --github you/notes --root ~/notes

--root を省略すると ~/.cache/kioq/<owner>/<repo> に自動配置。書き込みは GitHub API 経由で、rename_note 等の複数ファイル変更も 1 commit にまとまる。

MCP 設定例

ローカル

{
  "mcpServers": {
    "kioq": {
      "command": "npx",
      "args": ["@tomingtoming/kioq", "--root", "/absolute/path/to/notes"]
    }
  }
}

GitHub

{
  "mcpServers": {
    "kioq": {
      "command": "npx",
      "args": ["@tomingtoming/kioq", "--github", "you/notes"],
      "env": {
        "KIOQ_GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

提供ツール

読み取り

| ツール | 概要 | |--------|------| | search_notes | 日本語対応の全文検索（形態素分割 + CJK N-gram） | | read_note | ノート読み取り + リンク健全性 + 構造スコア + consolidation（AI睡眠）候補 | | recent_notes | 最近更新されたノート一覧 | | resolve_links | ノート内 WikiLink の解決状況 | | list_backlinks | 被リンク一覧 | | context_bundle | 関連ノートの優先度付き束 | | lint_structure | ノートルート全体の構造診断 + consolidation（AI睡眠）候補件数 | | memory_contract | AI 運用向けの構造化ルール |

書き込み

| ツール | 概要 | |--------|------| | write_note | ノート作成・更新 | | write_flow_note | 進行中の問い（Flow）を作成 | | promote_to_stock | Flow を Stock に昇格（1 commit で原子的に） | | append_note | 既存ノートに追記 | | rename_note | リネーム + 全バックリンク自動更新 | | delete_note | 削除 + 影響度レポート |

全ツールに response_mode=minimal|standard|verbose あり。

命名

• 機械向けの field 名と action 名は consolidation_* を使う
• AI睡眠 は人間向けの比喩として残す
• ここでいう consolidation は「要約・分割・Flow から Stock への切り出し」をまとめた後段統合作業を指す
• 実験的な旧ビルドで sleep_* が見えていても、現在の正準名は consolidation_*

環境変数

| 変数 | 説明 | デフォルト | |------|------|-----------| | KIOQ_ROOT | ノートルートのパス | (必須 / GitHub 時は自動) | | KIOQ_GITHUB | owner/repo 形式 | — | | KIOQ_GITHUB_TOKEN | GitHub token | — | | KIOQ_GITHUB_BRANCH | 対象ブランチ | main | | KIOQ_DEFAULT_DIRECTORY | 新規ノートの既定ディレクトリ | Inbox | | KIOQ_PREVIEW_LENGTH | 検索抜粋の最大文字数 | 320 | | KIOQ_INDEX_SCORE_THRESHOLD | index_like 判定の score 閾値 | 70 | | KIOQ_INDEX_SECTION_THRESHOLD | index_like 判定の section 数閾値 | 2 | | KIOQ_STALE_FLOW_DAYS | stale flow 判定の日数 | 7 |

全て -- 付き CLI 引数でも指定可能（例: --root, --github, --default-directory）。引数は環境変数より優先。

ドキュメント

• docs/architecture.md — アーキテクチャ
• docs/note-templates.md — stock / flow / index テンプレート
• docs/application-data-separation.md — アプリとデータの責務分離
• docs/index-note-pattern.md — 索引ノートパターン
• docs/source-metadata.md — source_ref 規約

開発

npm install
npm run check   # 型チェック
npm test        # ビルド + テスト