Define first-class MCP setup requirements for Repl.Mcp apps

[autocarl]

Requirement

Apps built with Repl.Mcp should have a first-class way to help users and agents connect the app's MCP server to their IDE/agent host without hand-maintaining fragile, copy/pasted setup instructions for every client.

The important requirement is not a specific implementation such as mcp setup, descriptor generation, or file mutation. The requirement is that a Repl.Mcp app can expose enough machine-readable and user-readable setup information for MCP clients and agent hosts to discover, configure, verify, and, where appropriate, register the server reliably.

Why this matters

Today Repl.Mcp gives an app an MCP entry point such as:

myapp mcp serve

Documentation and samples then explain how to copy that launch command into host-specific configuration files or CLI commands. That works, but the approach does not scale well:

• every MCP host has slightly different config shape and file locations;
• VS Code, Claude Desktop, Claude Code, Cursor, Codex, Cline, etc. do not all use the same registration model;
• local development launch commands differ from published app/package launch commands;
• config examples can drift from the actual server launch contract;
• users and coding agents need to know whether a server is already configured, missing, or outdated;
• direct file mutation is risky unless it supports dry-run, backups, JSON merge, and clear diagnostics;
• the MCP ecosystem is moving toward standard server metadata (server.json, registries, package metadata), so Repl.Mcp should not assume hand-written per-client JSON is the long-term source of truth.

User stories

• As an app author, I want to define how my app's MCP server should be launched once, so I do not have to maintain separate instructions for every agent host.
• As a user, I want to ask the app how to connect it to my IDE/agent, so I can avoid editing unknown JSON files by hand.
• As a coding agent, I want machine-readable setup/status output, so I can configure or diagnose the MCP server without guessing.
• As a maintainer, I want generated or validated setup output to stay aligned with myapp mcp serve, package metadata, and samples.
• As a security-conscious user, I want any automated installation to be previewable and reversible before files are changed.

Functional requirements

A Repl.Mcp app should be able to provide, directly or through Repl.Mcp infrastructure:

1. Canonical launch information

   • server id/name;
   • display name/description;
   • launch command and arguments;
   • transport type;
   • optional environment variables;
   • optional package metadata such as NuGet package id/version;
   • distinction between local-development launch and published-package/executable launch.

2. Client-facing setup output

   • at minimum, render or expose setup instructions/config for common MCP client shapes;
   • support machine-readable output for agents/automation;
   • avoid requiring app authors to duplicate host-specific snippets manually.

3. Status/diagnostics

   • report whether a supported client appears configured, missing, or outdated where detection is possible;
   • detect common launch/config pitfalls such as relative paths, missing executable/package runtime, wrong config shape, or local dev commands that rebuild on startup;
   • provide actionable remediation steps.

4. Safe optional registration

   • if Repl.Mcp supports writing configuration or delegating to client CLIs, it must support dry-run/preview;
   • avoid overwriting unrelated config;
   • back up or safely merge file-based configuration;
   • prefer official client CLI registration when available;
   • fail explicitly when a client cannot be safely modified.

5. Ecosystem compatibility

   • account for MCP server.json/registry/package metadata where applicable;
   • do not treat Repl.Mcp itself as the installable server; the app built with Repl.Mcp is the MCP server;
   • keep the model extensible for future client/registry conventions.

Possible solution directions

These are options to evaluate, not required design decisions.

Option A — config/status only

Expose commands such as:

myapp mcp config vscode --print
myapp mcp config claude-desktop --print
myapp mcp status --json

This avoids file mutation and gives users/agents reliable generated setup instructions.

Option B — setup/install commands

Expose commands such as:

myapp mcp setup vscode --dry-run
myapp mcp install claude-code
myapp mcp uninstall cursor

This is more convenient, but requires careful client adapters, safe file updates, and clear rollback behavior.

Option C — descriptor/manifest-first

Define a canonical Repl.Mcp setup/launch descriptor and project it into:

• server.json-style metadata;
• client-specific config snippets;
• status checks;
• optional install/uninstall adapters.

This may align best with the MCP registry/package direction, but the descriptor shape needs design.

Option D — documentation/sample helper only

For a minimal first step, Repl.Mcp could generate setup snippets for docs/samples without adding runtime install commands. This is less powerful but reduces drift immediately.

Candidate client shapes to consider

Not all of these need to be supported initially:

• generic mcpServers JSON;
• VS Code / GitHub Copilot .vscode/mcp.json top-level servers;
• Claude Code CLI registration;
• Codex CLI registration;
• Claude Desktop config;
• Cursor;
• Cline;
• Gemini CLI;
• OpenCode;
• JetBrains;
• Visual Studio;
• future registry-driven clients.

Non-goals / constraints

• Do not make a large hardcoded per-IDE/per-platform matrix the fundamental contract if a more durable metadata-based model is possible.
• Do not make file mutation the only or default path.
• Do not require every Repl.Mcp app to opt into full auto-install behavior.
• Do not generate config that can drift from the actual app launch path.
• Do not hide unsafe side effects behind a friendly setup command; preview and diagnostics must be first-class.

Acceptance criteria for initial design

Before implementation, decide:

• what setup/launch information a Repl.Mcp app must expose;
• which output is required for humans vs agents;
• whether the first release should include config generation only, status, install/uninstall, or a subset;
• how to represent local development vs published package launch;
• how this relates to MCP server.json and registries;
• which client shapes are stable enough to support initially;
• where this belongs (Repl.Mcp vs a separate package such as Repl.Mcp.Setup).

A first implementation should include tests that verify generated/status output stays aligned with the app's declared MCP launch contract.