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

canonical-vault-mcp-server

canonical-vault-mcp-server

읽기 전용 MCP 서버로, canonical-vault GitHub 저장소를 모든 MCP 클라이언트(GitHub Copilot, Claude, 또는 Streamable HTTP MCP를 지원하는 모든 도구)에 노출합니다.

다섯 가지 도구는 모두 읽기 전용이며, 모두 kushkillerjsixx66/canonical-vault로 범위가 제한됩니다:

도구

용도

vault_list_directory

경로의 파일/디렉터리 나열

vault_get_file

파일의 디코딩된 텍스트 콘텐츠 가져오기

vault_get_file_history

계보(lineage) — 경로의 커밋 기록

vault_get_commit

단일 커밋의 전체 세부 정보 + diff 통계

vault_search_files

저장소 전체 코드 검색

이 서버에는 의도적으로 쓰기 도구가 없습니다. 여기서는 커밋, 푸시, 또는 볼트 수정이 불가능합니다.


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 요청이 시간당 60회로 제한되고, 있으면 시간당 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 → 시작. Copilot Chat이 다섯 개의 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

설계 선택에 대한 참고 사항

  • 요청별 무상태(stateless) 전송: api/mcp.ts는 모든 POST에서 새 McpServer + StreamableHTTPServerTransport를 생성합니다. 이는 서버리스에 올바른 패턴입니다 — Vercel 함수는 호출 간 메모리를 유지하지 않으므로 유지할 세션이 없고, 두 호출자가 동시에 엔드포인트에 접근할 때 요청 ID 충돌도 피할 수 있습니다.

  • 계보(lineage) = 커밋 기록이며, 특별한 개념이 아닙니다 — 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