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).

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.