MCP and skills auto-install across all AI clients

Problem

When a user clones a repo that uses Dataface, there's no automatic way for their AI tools to discover the Dataface MCP server and skills. Today, dft mcp init only supports three clients (Cursor, Codex, Claude Desktop), and even those require the user to know the command exists and run it manually. Critical gaps:

1. VS Code / GitHub Copilot not supported. VS Code uses .vscode/mcp.json with a "servers" root key (not "mcpServers"). Copilot agent mode reads this file and auto-invokes tools — but dft mcp init never writes it.
2. Claude Code not supported. Claude Code reads .mcp.json at the project root. We don't write it.
3. GitHub Copilot Coding Agent not supported. Reads .github/copilot/mcp.json with "servers" key.
4. VS Code extension doesn't register MCP server. VS Code has a vscode.lm.registerMcpServerDefinitionProvider() API that lets extensions register MCP servers programmatically. Our extension doesn't use it — meaning even with the extension installed, Copilot can't see our tools.
5. Skills are file-copy only. Skills are copied to .cursor/skills/, .codex/skills/, etc. Clients like VS Code, Claude Code, and Copilot that don't read skill directories get no skills at all. The MCP spec has a prompts feature that could serve skills universally.
6. No zero-config path. There's no single project-level signal that says "this repo uses Dataface" — each client needs its own config file.

The fragmentation means every new AI tool requires a new code path in dft mcp init. We need a strategy that covers the current ecosystem AND handles new tools that enter it.

Context

Research doc: ai_notes/ai/MCP_SKILLS_AUTO_INSTALL.md — full analysis of config formats, detection heuristics, VS Code extension API, and skills distribution.

Existing infrastructure: - dft mcp init — CLI command that auto-detects and configures Cursor, Codex, Claude Desktop (dataface/cli/main.py:866) - _MCP_CLIENTS dict — maps client names to (config_path, servers_key, detect_path) (dataface/cli/main.py:854) - _upsert_mcp_config() — writes JSON config files, already handles different root keys (dataface/cli/main.py:818 and dataface/cli/commands/mcp.py:10) - _get_bundled_skills_dir() — finds bundled skills for file-based install (dataface/cli/commands/mcp.py:43) - 7 bundled skills in dataface/ai/skills/ — SKILL.md files for design, workflow, troubleshooting, etc. - MCP server already serves skills as resources (dataface://guide/*) via dataface/ai/mcp/server.py

Config format fragmentation (the core problem):

Related tasks: - task-m1-mcp-extension-copilot-tooling-contract.md — MCP tool contract hardening (P0) - task-m1-ide-copilot-mcp-dashboard-query-workflow.md — Copilot + MCP round-trip in extension (deferred to M2)

Possible Solutions

Option A: Expand dft mcp init Only [Baseline]

Add vscode, claude-code, and copilot targets to the existing _MCP_CLIENTS dict. Auto-detect new directories. Users still must run the command.

Trade-offs: Minimal code change. Still requires manual step. Doesn't solve the VS Code extension gap.

Option B: VS Code Extension Registers MCP Server via API [Recommended for Extension]

Use vscode.lm.registerMcpServerDefinitionProvider() to register the MCP server when the extension activates. Copilot automatically discovers tools — no config file needed.

Activation via workspaceContains:**/*.face.yml or presence of faces/ directory.

Trade-offs: Zero-config for VS Code users with the extension. Doesn't help non-VS-Code clients. Requires TypeScript extension work.

Option C: MCP Prompts for Universal Skills [Recommended for Skills]

Expose skills as MCP prompts (@server.list_prompts() / @server.get_prompt()). VS Code shows them as slash commands. Any MCP client can read them. No file copying needed.

Trade-offs: Works for every MCP client. Requires MCP server changes. File-based skills still needed for Cursor/Codex which read SKILL.md files directly.

Option D: .mcp.json at Project Root + dft mcp init --all [Recommended for New Projects]

Generate all config files at once for new projects. Include .mcp.json (Claude Code), .vscode/mcp.json (VS Code), .cursor/mcp.json (Cursor). One command configures everything.

Trade-offs: Repo gets several config files. But they're small, standard, and gitignore-friendly.

Recommended: All Four Combined

• A + D for CLI: expand dft mcp init to cover all clients with --all flag
• B for VS Code: extension registers MCP server via API
• C for skills: expose as MCP prompts alongside file-based distribution

Plan

Phase 1: Expand dft mcp init (M1 — Week 1)

Files to modify: - dataface/cli/main.py — add new clients to _MCP_CLIENTS, add --all flag - dataface/cli/commands/mcp.py — no changes needed (already generic)

Steps: 1. Add vscode → .vscode/mcp.json with "servers" key 2. Add claude-code → .mcp.json at project root with "mcpServers" key 3. Add copilot → .github/copilot/mcp.json with "servers" key 4. Update auto-detection: check for .vscode/, .github/, CLAUDE.md, AGENTS.md 5. Add --all flag that writes every config file at once 6. Update help text and the configuring-dataface-mcp skill doc 7. Test: run dft mcp init --all, verify all config files are correct, open in each client

Acceptance criteria: - dft mcp init auto-detects VS Code, Claude Code, Copilot in addition to existing clients - dft mcp init vscode writes correct .vscode/mcp.json with "servers" key - dft mcp init claude-code writes correct .mcp.json at project root - dft mcp init copilot writes correct .github/copilot/mcp.json - dft mcp init --all writes all config files - Copilot agent mode in VS Code can discover and call Dataface tools via .vscode/mcp.json

Phase 2: VS Code Extension Registers MCP Server (Deferred — extension not actively shipping)

The VS Code extension is not actively maintained or shipping. This phase is deferred until the extension is revived. For now, VS Code/Copilot users can use dft mcp init vscode to write .vscode/mcp.json (covered by Phase 1).

Phase 3: MCP Prompts for Skills (M1 — Week 2)

Files to modify: - dataface/ai/mcp/server.py — add @server.list_prompts() and @server.get_prompt() handlers

Steps: 1. Add prompt handlers that serve skill content from dataface/ai/skills/ 2. Map skill names to prompt names: dashboard-design, report-design, workflow, troubleshooting 3. Strip frontmatter and serve as prompt content 4. Test: connect MCP client, verify prompts appear and return correct content

Acceptance criteria: - VS Code shows Dataface skills as slash commands (e.g., /mcp.dataface.dashboard-design) - Any MCP client can call prompts/get and receive skill content - Existing MCP resource delivery continues to work (backwards compatible)

Phase 4: One-Click Install Badge (M1 — Week 3)

1. Generate vscode:mcp/install URL with Dataface server config
2. Add install badge to README, docs, and PyPI page
3. Test: click badge, verify MCP server is added to VS Code

Implementation Progress

• Added Phase 1 MCP client support in dataface/cli/main.py for vscode, claude-code, and copilot.
• Added --all support to dft mcp init and expanded auto-detection markers to .vscode/, .github/, CLAUDE.md, and AGENTS.md.
• Reused the shared MCP config upsert helper from dataface/cli/commands/mcp.py instead of keeping duplicate CLI logic.
• Added CLI regression coverage in tests/core/test_mcp_cli.py for root-key differences, workspace-marker auto-detection, and --all.
• Updated the configuring-dataface-mcp skill doc and MCP module usage text for the new clients.
• Left Phases 2-4 deferred as explicitly requested.

Review Feedback

• Targeted tests passed: uv run pytest tests/core/test_mcp_cli.py
• just ci was run twice. Both failures were outside this change:
• First run: tests/faketran/test_application_models.py::test_fake_companies_populate_application_database_models[fake_companies.pied_piper-240-23] hit a timeout under parallel CI; the same test passed in isolation.
• Second run: tests/core/test_render_cli.py::TestRenderFile::test_render_file_terminal_format failed on a DuckDB file lock against examples/examples.duckdb under parallel CI.
• [x] Review cleared