MCP Setup

MCP Setup with the Web Editor

Goal: turn an existing project into an MCP server the web editor can manage (decorators → registry → tool templates → generated server).

Quick start

• Pick a server name (e.g., demo) and mirror/rename the project to mcp_demo/.
• Drop a facade file (service.py or demo_service.py) using references/service_facade_template.py and add @mcp_service to each exported function.
• Seed mcp_editor/mcp_demo/tool_definition_templates.py from references/tool_definition_templates_sample.py so the web editor has defaults.
• Add a mcp_demo profile block to mcp_editor/editor_config.json (see references/editor_config_snippet.json).
• Run python mcp_editor/tool_editor_web.py, verify auto-scan picked up the decorators, adjust schemas, then Save to emit tool_definitions.py.
• Generate the server when ready: python jinja/generate_universal_server.py demo (do not hand-edit generated files).

Workflow

1. Prepare the target project

• Normalize naming: folders and editor config keys should be mcp_{server}. Place server code under mcp_{server}/mcp_server/.
• Keep business logic importable by the facade (no heavy side effects on import; move those behind functions).

2. Select functions to expose (agent-assisted)

• Scan for public, side-effect-safe entry points that return serializable data or clear status (controllers, service layer, use-cases). Prefer functions with simple parameters over deeply coupled internals.
• Extract docstrings/comments for descriptions and note default values/Optional hints. Avoid exposing constructors or low-level helpers unless necessary.

3. Build the facade with decorators

• Start from references/service_facade_template.py; copy to mcp_{server}/{server}_service.py (or service.py).
• For each exposed function, wrap the underlying call and annotate with @mcp_service(tool_name=..., server_name=..., service_name=..., description=..., tags=..., category=...).
• Keep return values JSON-serializable. If you need richer types, define Pydantic models in {server}_types.py and import them.
• Prefer pure wrappers so scanning stays stable; avoid doing I/O at module import time.

4. Register services

• Launch the web editor (python mcp_editor/tool_editor_web.py) to auto-scan @mcp_service and refresh registry_{server}.json, or run python mcp_editor/mcp_service_registry/mcp_service_scanner.py directly.
• Confirm the registry entry shows tool_name, server_name, and the correct implementation module/method.

5. Seed tool templates (LLM-facing schemas)

• Copy references/tool_definition_templates_sample.py to mcp_editor/mcp_{server}/tool_definition_templates.py and align entries with your decorated functions.
• Use mcp_editor/mcp_service_registry/mcp_service_decorator.generate_inputschema_from_service if you want to auto-derive a starting inputSchema from the captured signature; then refine descriptions and required fields.
• Keep MCP_TOOLS in sync with the facade: names, signatures, and targetParam mappings should mirror the @mcp_service parameters. Include at least one default entry so the editor UI is not empty.

6. Wire the web editor profile

• Add a profile block in mcp_editor/editor_config.json keyed by mcp_{server}: template path, output path, optional types_files, and port/host. Use references/editor_config_snippet.json as a shape guide.
• If you prefer templating, regenerate via python jinja/generate_editor_config.py after editing the template.

7. Generate and validate

• In the web editor, adjust schemas/internal args as needed and click Save to write mcp_{server}/mcp_server/tool_definitions.py.
• Generate the server scaffold when ready: python jinja/generate_universal_server.py {server}. Do not edit generated server.py or tool_definitions.py directly; modify templates/facades instead.
• Smoke test: python mcp_{server}/mcp_server/server.py then invoke one tool manually to confirm wiring.

Agent notes for auto-extraction

• Use heuristics to rank candidate functions: high-level orchestration, minimal side effects, good docstrings, and parameters that map cleanly to JSON. Skip functions requiring global state unless you can inject dependencies in the facade.
• When unsure about parameter schemas, default to strings and mark optional; let the web editor refine types. Populate description from docstrings/comments.
• Always add a couple of safe defaults (health/ping, list/sample) in tool_definition_templates.py so users see working examples immediately.

References to load when needed

• .claude/skills/mcp-setup/references/service_facade_template.py — facade + decorator usage example.
• .claude/skills/mcp-setup/references/tool_definition_templates_sample.py — minimal MCP_TOOLS template with two sample tools.
• .claude/skills/mcp-setup/references/editor_config_snippet.json — profile block shape for mcp_{server}.
• Project docs: mcp_editor/tool_editor_web.py, .claude/commands/web-editor.md, .claude/commands/terminology.md, mcp_editor/mcp_service_registry/mcp_service_decorator.py for decorator details.