feat(deploy): Streamable-HTTP MCP entrypoint and Azure deployment

[miguelgfierro]

Summary

• New firefly-mcp-http CLI: minimal FastAPI app exposing FastMCP at /mcp over Streamable HTTP plus /healthz. Reuses create_mcp_app(); bypasses mount_http (which doesn't wire FastMCP's lifespan into the parent FastAPI — tools/list returns 500 otherwise).
• Four MCP tools via corpus_rag.py: ingest_corpus_filesystem, ingest_corpus_sharepoint, corpus_retrieve, corpus_query — backed by library-grade CorpusAgent (MarkdownChunker + SqliteVec + hybrid retrieval + reranker + answerer).
• Multi-stage Dockerfile (uv sync --extra rest --extra mcp, non-root, CMD ["firefly-mcp-http"]).
• .github/workflows/deploy-mcp.yml — OIDC login → ACR build/push → az containerapp update.
• docs/deploy/corpus-persistence.md — operator guide for durable CORPUS_ROOT on Azure Container Apps.

Auth model

No framework-level API keys. Auth belongs at the experience layer (Container Apps EasyAuth, future dedicated auth service) per the zero-trust direction in #98 — the framework itself stays unaware of bearer tokens.

Running locally and connecting to Claude Code

1. Copy and fill the template:

cp .env.template .env
# Fill in ANTHROPIC_API_KEY, EMBEDDING_BINDING_HOST, EMBEDDING_BINDING_API_KEY, etc.
# Set CORPUS_ROOT to an absolute path on your machine (not $PWD — dotenv doesn't expand shell vars)

2. Start the server:

uv run dotenv -f .env run -- firefly-mcp-http
# Server starts on PORT from .env (default 8080). Verify with:
curl http://localhost:8080/healthz   # → {"status":"ok"}

3. Register with Claude Code (once):

claude mcp add --transport http --scope user firefly-rag http://localhost:8080/mcp/

4. Test in Claude Code:

Ingest a local folder first (replace my-corpus and path as needed):

Use ingest_corpus_filesystem — corpus_id "my-corpus", root_path "/absolute/path/to/docs"

Then query it:

Use corpus_retrieve — corpus_id "my-corpus", question "what is this about?", top_k 5
Use corpus_query — corpus_id "my-corpus", question "summarise the key topics"

corpus_retrieve returns raw ranked chunks (no LLM answer) — useful for judging retrieval quality independently. corpus_query runs the full pipeline and returns a grounded answer with citations.

Azure resources (already provisioned in rg-firefly, spaincentral)

Resource	Name	Notes
Log Analytics	firefly-logs	PerGB2018, 30-day retention.
ACR	fireflysignature	Basic, admin disabled.
Storage + blob	fireflysignature / firefly-artifacts	StorageV2, LRS, public access disabled.
Key Vault	kv-firefly-signature	RBAC-mode, purge-protection on.
User-assigned MI	firefly-mcp-mi	Roles: AcrPull on ACR, Storage Blob Data Contributor on Storage, Key Vault Secrets User on KV.
Federated credential	on firefly-mcp-mi	Issuer token.actions.githubusercontent.com, subject repo:fireflyframework/fireflyframework-agentic:ref:refs/heads/main, audience api://AzureADTokenExchange.
Container Apps env	firefly-env	Wired to firefly-logs.
Container App	firefly-mcp	Ingress external port 8000; min 0 / max 3 replicas; 0.5 CPU / 1 Gi; ACR auth via the user-assigned MI. URL: https://firefly-mcp.mangosmoke-5d24814d.spaincentral.azurecontainerapps.io.

GitHub repo secrets AZURE_CLIENT_ID / AZURE_TENANT_ID are already configured for the workflow.

Verification

• Local: docker buildx build -t firefly-mcp:dev ., docker run -p 8000:8000 → /healthz 200, MCP initialize returns {"name":"firefly","version":"3.2.4"}, tools/list returns the four corpus RAG tools.
• Azure: same /healthz and MCP handshake succeed over HTTPS at the URL above.
• Unit: pytest tests/unit/cli/test_mcp_http.py — 2 passing.

Refs: #98

Test plan

• Copy .env.template → .env, fill credentials, start with uv run dotenv -f .env run -- firefly-mcp-http.
• Register with Claude Code: claude mcp add --transport http --scope user firefly-rag http://localhost:8080/mcp/.
• Ingest a local folder via ingest_corpus_filesystem and verify counts returned.
• Run corpus_query and confirm grounded answer with citations.
• Re-run unit tests: uv run pytest tests/unit/cli/.
• Build image locally with docker buildx build and probe /healthz + MCP initialize.
• Decide and wire EasyAuth (Entra ID) on firefly-mcp before exposing the URL beyond internal use.

[miguelgfierro]

End-to-end auth flow: SharePoint → Claude Code

There are two separate phases: indexing (done once or on a schedule) and querying (every user session).

---

Phase 1 — Indexing: SharePoint → SQLite corpus on Azure

Runs inside the firefly-mcp Container App. The admin calls ingest_corpus_sharepoint(corpus_id, drive_id) via MCP.

1. ManagedIdentityCredential() calls the Azure IMDS endpoint (internal to the Container App infrastructure) and receives a short-lived Microsoft Graph token for the firefly-mcp-mi managed identity — no secrets, no config needed.
2. SharePointSource calls GET /drives/{drive_id}/root/delta on Graph to list changed files.
3. Each file is downloaded, converted to Markdown (MarkitdownLoader), split into ~600-token chunks (MarkdownChunker), embedded (AzureEmbedder → Azure OpenAI), and written to corpus.sqlite on the Azure Files share mounted at CORPUS_ROOT.
4. A delta cursor is saved so the next run only fetches changes.

Prerequisite: firefly-mcp-mi must be granted Sites.Selected (preferred) or Sites.Read.All in Entra ID for the target SharePoint site.

---

Phase 2 — Querying: user in Claude Code → answer

The user's ~/.claude/settings.json points at the MCP server URL. When they ask a question, Claude calls corpus_query(corpus_id, question) over Streamable HTTP:

1. QueryExpander — Claude Haiku generates 3–5 query variants.
2. HybridRetriever — BM25 (FTS5) + dense (vec0) search over corpus.sqlite.
3. HaikuReranker — Claude Haiku ranks the top-20 candidates.
4. AnswerAgent — Claude Sonnet produces a grounded answer with citations.

The SharePoint data never leaves Azure. The user receives only the answer text and source references.

---

Who authenticates what

Actor	Target	Mechanism
GitHub Actions (CI/CD)	Azure ACR + Container Apps	OIDC federated credential on firefly-mcp-mi
firefly-mcp container	SharePoint / Microsoft Graph	Managed Identity via IMDS — zero config
firefly-mcp container	Azure OpenAI (embedder)	EMBEDDING_BINDING_API_KEY env var
Claude Code user	firefly-mcp HTTP endpoint	Not yet implemented — EasyAuth/Entra planned (see test plan)

---

Proposed: Claude Code user auth via Container Apps EasyAuth (respects #98)

The architecture from #98 places auth at the experience layer (ingress), keeping the framework process completely unaware of credential material. The simplest implementation is Container Apps EasyAuth — it sits at the Container App ingress, the Python process is untouched.

Claude Code
  │  POST /mcp
  │  Authorization: Bearer <entra_token>
  │
  ▼
Container Apps EasyAuth  (ingress — never hits Python)
  → validates token against Entra ID tenant
  → invalid/missing → 401 immediately
  → valid → forwards request + adds X-MS-CLIENT-PRINCIPAL headers
  │
  ▼
firefly-mcp Python process
  (sees a normal MCP request, never touches auth)

Implementation — no framework code changes needed

1. Create an Entra App Registration

az ad app create --display-name "firefly-mcp" --sign-in-audience AzureADMyOrg
APP_ID=$(az ad app list --display-name "firefly-mcp" --query '[0].appId' -o tsv)
az ad sp create --id $APP_ID

2. Enable EasyAuth on the Container App

az containerapp auth microsoft update \
  -g rg-firefly -n firefly-mcp \
  --client-id $APP_ID \
  --tenant-id <tenant-id>

az containerapp auth update \
  -g rg-firefly -n firefly-mcp \
  --unauthenticated-client-action Return401

Return401 is critical — API clients (Claude Code) cannot follow a login redirect.

3. Claude Code users configure their token

# Acquire token (valid ~1 hour)
az account get-access-token --resource api://$APP_ID --query accessToken -o tsv

// ~/.claude/settings.json
{
  "mcpServers": {
    "firefly": {
      "url": "https://firefly-mcp.mangosmoke-5d24814d.spaincentral.azurecontainerapps.io/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

A small wrapper script can automate token refresh before each session:

TOKEN=$(az account get-access-token --resource api://$APP_ID --query accessToken -o tsv)
jq --arg t "$TOKEN" '.mcpServers.firefly.headers.Authorization = "Bearer \($t)"' \
  ~/.claude/settings.json > /tmp/s.tmp && mv /tmp/s.tmp ~/.claude/settings.json

Why this respects #98

• The firefly-mcp Python process is zero-auth-aware — no msal, no token parsing, no validation code.
• EasyAuth is the "capa de experiencia" from Autenticación del framework #98: it sits at the WAN boundary; downstream layers receive requests only after validation.
• When the architecture graduates to a dedicated auth service, EasyAuth is replaced by that service — the container needs no changes.
• The token_provider callable pattern already in SharePointSource follows the same principle for the inbound (Graph) direction.