Skip to main content
Glama
canonical-vault-mcp-server

canonical-vault-mcp-server

canonical-vault-mcp-server

canonical-vault GitHub リポジトリをあらゆる MCP クライアント(GitHub Copilot、Claude、その他 Streamable HTTP MCP に対応するもの)に公開する読み取り専用 MCP サーバー。

5 つのツールはすべて読み取り専用で、すべて kushkillerjsixx66/canonical-vault にスコープされています:

ツール

目的

vault_list_directory

パス上のファイル/ディレクトリを一覧表示

vault_get_file

ファイルのデコード済みテキストコンテンツを取得

vault_get_file_history

系統 — パスのコミット履歴

vault_get_commit

1つのコミットの完全な詳細 + diff 統計

vault_search_files

リポジトリ全体のコード検索

このサーバーには意図的に書き込みツールは存在しません。ここから vault にコミット、プッシュ、変更を行うことはできません。


1. Vercel へのデプロイ

npm install -g vercel   # if you don't have it
cd canonical-vault-mcp-server
vercel login
vercel

デフォルトを受け入れてください(Vercel は api/mcp.ts を Node サーバーレス関数として自動検出します)。vercel --prod の後、次のような URL が得られます:

https://canonical-vault-mcp-server.vercel.app

MCP エンドポイントは次のとおりです:

https://canonical-vault-mcp-server.vercel.app/api/mcp

環境変数(Vercel ダッシュボード → Settings → Environment Variables で設定)

変数

必須

デフォルト

備考

GITHUB_TOKEN

強く推奨

なし

repo(または vault が公開されているため public_repo のみ)読み取りスコープを持つ GitHub PAT。これがない場合、すべての呼び出し元で共有される GitHub API リクエストは 1 時間あたり 60 回に制限されます。あれば 1 時間あたり 5000 回です。

GITHUB_OWNER

いいえ

kushkillerjsixx66

リポジトリが移動した場合のみ変更

GITHUB_REPO

いいえ

canonical-vault

リポジトリ名が変更された場合のみ変更

GITHUB_DEFAULT_REF

いいえ

main

ref が指定されない場合にツールが読み取るデフォルトブランチ

環境変数を追加したら、関数がそれを取得できるように再デプロイ(vercel --prod)してください。


Related MCP server: GitHub MCP

2. GitHub Copilot を接続する

Copilot(VS Code 内、および Copilot コーディングエージェント)は、ワークスペース内の .vscode/mcp.json または VS Code のグローバル MCP 設定から MCP サーバー設定を読み取ります。追加:

{
  "servers": {
    "canonical-vault": {
      "type": "http",
      "url": "https://canonical-vault-mcp-server.vercel.app/api/mcp"
    }
  }
}

次に VS Code で: コマンドパレット → "MCP: List Servers" → canonical-vault → Start。Copilot Chat は 5 つの vault_* ツールを自動的に認識し、エージェントモードで呼び出すことができます。

Copilot のリモートコーディングエージェント(VS Code ローカルではない)の場合、同じ URL を github.com の組織の MCP サーバー設定に登録できます。Copilot のエージェント MCP 設定がプランに応じて存在する場所です。その部分は GitHub 側の責任であり、このサーバーの責任ではありません。


3. ローカルテスト(デプロイ前)

npm install
npm run build
npx @modelcontextprotocol/inspector node dist/index.js

これにより MCP Inspector UI が開き、Copilot を接続する前にライブリポジトリに対して各ツールを手動で呼び出すことができます。

stdio の代わりにローカルで HTTP パスをテストするには:

npm install -g vercel
vercel dev
# endpoint: http://localhost:3000/api/mcp

設計上の選択に関するメモ

  • ステートレスなリクエストごとのトランスポート: api/mcp.ts は POST のたびに新しい McpServer + StreamableHTTPServerTransport を作成します。これはサーバーレスに適したパターンです。Vercel 関数は呼び出し間でメモリを保持しないため、維持するセッションはなく、2 つの呼び出し元が同時にエンドポイントにヒットした場合のリクエスト ID の衝突も回避できます。

  • 系統 = コミット履歴。特別な概念ではありません。vault_get_file_history は文字通り GET /commits?path=... であり、「系統」を GitHub の API が実際に提供するものに最も正直にマッピングしたものです。vault の系統チェーン概念(ガバナンス/vault パイプライン)がより具体的なものを必要とする場合(例: リポジトリ内にある系統マニフェストファイルの読み取り)、git 履歴を再実装するよりも、vault_get_file をそのマニフェストに直接向ける方が適しています。

  • 設計上読み取り専用(ご回答に基づく): このサーバーは canonical-vault に書き込むことはできません。後で Copilot にコミットバックさせたい場合(例: PR 経由)は、実際の破壊的操作のレビューを伴う別の書き込みツールセットであり、静かに追加するものではありません。

  • 検索の注意点: GitHub のコード検索 API はデフォルトブランチのみをインデックスし、独自の伝播遅延があります。数秒前にコミットされたファイルは vault_search_files にまだ表示されない可能性があります。vault_get_file と vault_list_directory は常にライブツリーを反映します。

Available Tools

5 tools
vault_get_commitGet Vault Commit DetailA
Read-onlyIdempotent

Get full detail for a single commit in canonical-vault: message, author, stats, and the list of files it changed (with per-file diff stats).

Args:

  • sha (string): Full or abbreviated commit SHA (get one from vault_get_file_history)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "sha": string, "message": string, "author": string, "date": string, "stats": {...}, "files": [{ "filename": string, "status": string, "additions": number, "deletions": number }] }

Examples:

  • Use when: "What exactly changed in commit a1b2c3d?" -> sha="a1b2c3d"

  • Don't use when: You just want the commit list for a path (use vault_get_file_history instead)

Error Handling:

  • Returns "Error: ... not found" if the SHA doesn't exist in this repo

Inputs: sha (required), response_format.

vault_get_fileGet Vault FileA
Read-onlyIdempotent

Fetch the decoded text content of a single file from the canonical-vault repository (kushkillerjsixx66/canonical-vault).

Args:

  • path (string): File path relative to repo root, e.g. 'governance/CONSTITUTION.md'

  • ref (string): Branch, tag, or commit SHA (default: 'main')

Returns: The raw file text, prefixed with a small header (path, ref, sha, size). Binary or oversized files (> 500000 bytes) return an error instead of garbled content.

Examples:

  • Use when: "Read me the current Constitution" -> path="governance/CONSTITUTION.md"

  • Use when: "What does vara.py look like right now?" -> path="vara.py"

  • Don't use when: You just want to know if a file exists or how big it is (use vault_list_directory instead)

Error Handling:

  • Returns "Error: ... not found" if the path doesn't exist on that ref

  • Returns an error for directories (use vault_list_directory instead) or binary files

Inputs: path (required), ref.

vault_get_file_historyGet Vault File/Path LineageA
Read-onlyIdempotent

Get the commit lineage (history) affecting a file or directory in canonical-vault — i.e. every commit that touched that path, most recent first.

Args:

  • path (string): File or directory path to trace (default: "" for whole-repo history)

  • ref (string): Branch, tag, or commit SHA to start from (default: 'main')

  • limit (number): Max commits to return, 1-100 (default: 20)

  • offset (number): Commits to skip for pagination (default: 0)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "path": string, "count": number, "commits": [{ "sha": string, "message": string, "author": string, "date": string, "url": string }], "has_more": boolean }

Examples:

  • Use when: "How has VARA_SPEC_1.0 evolved?" -> path="system-specs/VARA_SPEC_1.0.md"

  • Use when: "What's the recent commit lineage for the whole vault?" -> path=""

  • Don't use when: You need the full diff of one specific commit (use vault_get_commit instead)

Error Handling:

  • Returns "Error: ... not found" if the path or ref doesn't exist

Inputs: ref, path, limit, offset, +1 more.

vault_list_directoryList Vault DirectoryA
Read-onlyIdempotent

List the files and subdirectories at a given path in the canonical-vault repository (kushkillerjsixx66/canonical-vault).

Args:

  • path (string): Directory path relative to repo root (default: "" for root)

  • ref (string): Branch, tag, or commit SHA (default: 'main')

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "path": string, "ref": string, "entries": [{ "name": string, "path": string, "type": "file"|"dir", "size": number }] }

Examples:

  • Use when: "What's in the governance directory?" -> path="governance"

  • Use when: "Show me the top-level structure of the vault" -> path=""

  • Don't use when: You need the actual contents of a file (use vault_get_file instead)

Error Handling:

  • Returns "Error: ... not found" if the path doesn't exist on that ref

  • Returns a rate limit message if GitHub's API limit is exceeded (set GITHUB_TOKEN to raise it)

Inputs: ref, path, response_format.

vault_search_filesSearch Vault FilesA
Read-onlyIdempotent

Search file names and contents across the canonical-vault repository (kushkillerjsixx66/canonical-vault) using GitHub code search.

Args:

  • query (string): Search terms. Supports GitHub code search qualifiers like 'path:governance' or 'extension:md'

  • limit (number): Max results, 1-50 (default: 20)

  • offset (number): Results to skip for pagination (default: 0)

  • response_format ('markdown' | 'json'): Output format (default: 'markdown')

Returns: For JSON format: { "total": number, "count": number, "results": [{ "path": string, "url": string }], "has_more": boolean }

Examples:

  • Use when: "Where is Coherence defined?" -> query="Coherence path:governance"

  • Use when: "Find every mention of vara.py" -> query="vara.py"

  • Don't use when: You already know the exact path (use vault_get_file instead)

Error Handling:

  • Returns "No files found matching ''" if the search returns empty

  • GitHub code search only indexes the default branch and repos under ~size limits; very new commits may lag briefly

Inputs: query (required), limit, offset, response_format.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a distinctly separate purpose: listing a directory, reading a file, tracing commit history, inspecting a single commit, and searching the repository. The descriptions even include explicit 'Don't use when' guidance to prevent confusion.

    Naming Consistency5/5

    All tools follow a uniform `vault_` prefix with a verb_noun pattern (list_directory, get_file, get_file_history, get_commit, search_files). Naming is idiomatic, consistent, and immediately signals the action and target.

    Tool Count5/5

    Five tools is a well-scoped set for a read-only repository browsing server. Each tool covers a core operation without redundancy or bloat, making the surface easy to grasp and use.

    Completeness5/5

    For a read-only vault browsing use case, the set fully covers the necessary operations: navigating (list), reading content (get file), exploring change history (history/commit), and searching. There are no obvious missing capabilities that would block an agent.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers