canonical-vault-mcp-server
canonical-vault-mcp-server
Read-only MCP-Server, der das GitHub-Repo canonical-vault für jeden MCP-Client bereitstellt — GitHub Copilot, Claude oder alles andere, das Streamable HTTP MCP spricht.
Fünf Tools, alle schreibgeschützt, alle beschränkt auf kushkillerjsixx66/canonical-vault:
Tool | Zweck |
| Dateien/Verzeichnisse unter einem Pfad auflisten |
| Den dekodierten Textinhalt einer Datei abrufen |
| Herkunft — Commit-Verlauf für einen Pfad |
| Vollständige Details + Diff-Statistiken für einen Commit |
| Codesuche im gesamten Repo |
In diesem Server gibt es absichtlich keine Schreib-Tools — nichts hier kann committen, pushen oder das Vault verändern.
1. Auf Vercel bereitstellen
npm install -g vercel # if you don't have it
cd canonical-vault-mcp-server
vercel login
vercelÜbernimm die Standardeinstellungen (Vercel erkennt api/mcp.ts automatisch als Node-Serverless-Funktion). Nach vercel --prod erhältst du eine URL wie:
https://canonical-vault-mcp-server.vercel.appDein MCP-Endpunkt ist:
https://canonical-vault-mcp-server.vercel.app/api/mcpUmgebungsvariablen (festlegen im Vercel-Dashboard → Settings → Environment Variables)
Variable | Erforderlich | Standard | Hinweise |
| Dringend empfohlen | keine | Ein GitHub-PAT mit |
| Nein |
| Nur ändern, falls das Repo umzieht. |
| Nein |
| Nur ändern, falls das Repo umbenannt wird. |
| Nein |
| Standard-Branch, aus dem die Tools lesen, wenn kein |
Nach dem Hinzufügen der Umgebungsvariablen erneut bereitstellen (vercel --prod), damit die Funktion sie übernimmt.
Related MCP server: GitHub MCP
2. GitHub Copilot damit verbinden
Copilot (in VS Code und im Copilot-Coding-Agent) liest die MCP-Server-Konfiguration aus .vscode/mcp.json in deinem Workspace oder aus den globalen MCP-Einstellungen von VS Code. Füge Folgendes hinzu:
{
"servers": {
"canonical-vault": {
"type": "http",
"url": "https://canonical-vault-mcp-server.vercel.app/api/mcp"
}
}
}Dann in VS Code: Command Palette → „MCP: List Servers“ → canonical-vault → Start. Copilot Chat erkennt die fünf vault_*-Tools automatisch und kann sie im Agent-Modus aufrufen.
Für den Remote-Coding-Agent von Copilot (nicht lokal in VS Code) kann dieselbe URL unter den MCP-Server-Einstellungen deiner Organisation auf github.com registriert werden, wo auch immer die Agent-MCP-Konfiguration von Copilot für deinen Plan liegt — dieser Teil liegt auf der Seite von GitHub, nicht auf der dieses Servers.
3. Lokales Testen (vor der Bereitstellung)
npm install
npm run build
npx @modelcontextprotocol/inspector node dist/index.jsDies öffnet die MCP-Inspector-Oberfläche, auf der du jedes Tool manuell gegen das Live-Repo aufrufen kannst, bevor du Copilot daran anbindest.
Um den HTTP-Pfad lokal statt über stdio zu testen:
npm install -g vercel
vercel dev
# endpoint: http://localhost:3000/api/mcpAnmerkungen zu Designentscheidungen
Zustandsloser Transport pro Anfrage:
api/mcp.tserstellt bei jedem POST einen neuenMcpServer+StreamableHTTPServerTransport. Dies ist das korrekte Muster für Serverless — Vercel-Funktionen behalten keinen Speicher zwischen Aufrufen, es gibt also keine Sitzung, die aufrechterhalten werden muss, und es vermeidet Kollisionen von Anfrage-IDs, wenn zwei Aufrufer gleichzeitig den Endpunkt treffen.Herkunft = Commit-Verlauf, kein maßgeschneidertes Konzept —
vault_get_file_historyist wörtlichGET /commits?path=..., was die ehrlichste Abbildung von „Herkunft“ auf das ist, was die GitHub-API tatsächlich bietet. Wenn das Konzept der Herkunftskette deines Vaults (Governance/Vault-Pipeline) etwas Spezifischeres benötigt — z. B. das Lesen einer Herkunfts-Manifestdatei, die im Repo liegt —, ist es besser,vault_get_filedirekt auf dieses Manifest zu richten, anstatt die Git-Historie neu zu implementieren.Von Natur aus schreibgeschützt, gemäß deiner Antwort — dieser Server kann nicht in canonical-vault schreiben. Wenn du später möchtest, dass Copilot committet (z. B. über einen PR), ist das ein separater Satz von Schreib-Tools mit echter Überprüfung destruktiver Aktionen, nicht etwas, das man stillschweigend anhängt.
Einschränkung bei der Suche: Die Code-Suche-API von GitHub indexiert nur den Standard-Branch und hat eine eigene Indexierungsverzögerung — eine Datei, die vor Sekunden committet wurde, erscheint möglicherweise noch nicht in
vault_search_files.vault_get_fileundvault_list_directoryspiegeln immer den Live-Baum wider.
Available Tools
5 toolsvault_get_commitGet Vault Commit DetailARead-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 FileARead-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 LineageARead-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 DirectoryARead-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 FilesARead-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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Unofficial GitHub MCP — wraps the GitHub public REST API (no auth required for public endpoints)
Access the GitHub API, enabling file operations, repository management, search functionality, and…
Public read-only MCP server for Genvernium product and developer resources.
Public read-only MCP for products, frameworks, guides, methodology, and blog metadata.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables searching GitHub code with filters and reading arbitrary file contents from any repository via MCP.GPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables self-hosted, read-only remote interaction with GitHub repositories, allowing listing repositories, searching code, and inspecting commits, pull requests, issues, and diffs via authenticated MCP clients.MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only browsing and querying of GitHub repositories, including listing repos, reading files, fetching READMEs, searching code, and viewing commit history via MCP.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to extract and inspect GitHub repository information, including repository summaries, directory structure, and file contents.-