mcp-vault

Eigenbau-MCP fuer Kunden-Markdown-Vaults die in SharePoint leben. Status: Draft, Block 1.1 done (2026-05-14).

Was er macht

Wrapt Microsoft Graph fuer ein einzelnes Kunden-Vault. Vault-relative Pfade statt SharePoint-Sites + Item-IDs (09_Standards/Regeln/Artifact-Design.md statt /sites/.../drive/items/01ZTQ6EZWIQL...). Office-Files (.docx, .xlsx) werden bei Bedarf zu Text geparsed. Zwei Auth-Modi: Service-Principal (single user / cron) und delegated OAuth (multi-user hinter mcp-vf-hosted).

Tools (Spec)

Tool	Stand 2026-05-14
vault_list_dir(path, recursive=False)	Code da (Block 1.1), ungetestet
vault_read_file(path)	Code da fuer .md/.txt, .docx/.xlsx Block 2
vault_get_metadata(path)	Code da
vault_search_text(query, path?, limit)	Stub (Block 2)
vault_get_context(path?)	Stub (Block 2)

Spec mit voller Tool-Surface: tool-surface.

Block-Plan

Block	Was	Status
1.1	Repo-Skelett (pyproject, README, env, settings, m365_backend, server)	done 2026-05-14
1.2	Service-Principal-Smoke: install + .env aus mcp-m365 + curl-Test der 3 Read-Tools	naechster Schritt
2	docx/xlsx Parser + vault_search_text + vault_get_context	pending
3	token_store.py + delegated.py (DynamoDB-Adapter, MSAL-Refresh) — parallel auch in mcp-m365 v0.3	pending
4	mcp-vf-hosted: OAuth-Callback-Route + vf-vault als 4. Sub-MCP einbinden	pending
5	CDK (DynamoDB + KMS + Secrets) + Deploy + End-to-End-Smoke	pending

Setup

Service-Principal lokal:

uv tool install --force --editable ~/source/mcps/mcp-vault
cp ~/source/mcps/mcp-vault/.env.local.example ~/source/mcps/mcp-vault/.env.local
# Werte eintragen — fuer VF reicht copy aus mcp-m365/.env.local plus:
#   VAULT_SITE_ID=vibefactorygbr.sharepoint.com,7fedd31b-b64d-4153-89ea-e14203438ad2,615d2455-91ac-4538-af8b-a3850b82c1a5
#   VAULT_ROOT=Workshop/VibeFactory
#   VAULT_NAME=vibe-factory
~/source/mcps/mcp-vault/start.sh
# laeuft auf http://127.0.0.1:8770/mcp

Konvention

Eine mcp-vault-Instanz pro Kunde. Zweiter Kunde mit eigenem Vault → eigene Instanz mit eigenem Port (z.B. 8771).

Auth-Modi

• M365_AUTH_MODE=service-principal (default): App-only-Token via ClientSecretCredential. Token-Cache in-memory. Fuer lokales Marvin-Setup + Cron-Routinen.
• M365_AUTH_MODE=delegated: Per-User-Token aus DynamoDB mcp-vf-m365-tokens, Refresh via MSAL. Subject kommt vom Mono-MCP (mcp-vf-hosted) als JWT-sub. Implementierung Block 3.

Architektur-Entscheidungen (approved 2026-05-14)

Aus open-decisions-vor-bau:

1. Eigenes Repo (nicht Teil von mcp-m365). Wiederverwendbar fuer andere Kunden mit SharePoint-Vault
2. JWT-sub als User-Subject, kein extra Header
3. DynamoDB in av-production, Tabellen-Prefix per Kunde
4. M365_AUTH_MODE=service-principal bleibt Default — Marvin lokal + Cron unbeeindruckt

Cross-Refs

• mcp-m365 — Cousin, low-level Graph-Wrapper
• mcp-vf-hosted — Mono der mcp-vault als Sub-MCP mounten wird (Block 4)
• sprint-2a-spec — kompletter Bau-Plan
• vf-vault-architektur — Gesamtkontext
• 2026-05-13-vf-vault-analyse — VF-Vault-Inventar (Source)