mcp-setup
Use when converting an existing Python project into an MCP server via the web editor: create an mcp_{server} folder, build a facade service.py with @mcp_service, auto-pick key functions to expose, seed tool_definition_templates.py with defaults, and wire editor_config.json so the tool editor can generate tool_definitions.py/server.py.
When & Why to Use This Skill
The MCP Setup skill automates the transformation of existing Python projects into Model Context Protocol (MCP) servers. By streamlining the creation of service facades, tool templates, and configuration files, it enables developers to quickly expose local code as functional tools for AI agents with minimal manual overhead and high schema accuracy.
Use Cases
- Legacy Code Integration: Quickly wrap existing Python business logic and utility libraries into an MCP-compliant server for use with Claude and other AI agents.
- Automated Tool Generation: Use @mcp_service decorators and web-based scanning to automatically derive JSON schemas and tool definitions from Python function signatures.
- Standardized Infrastructure: Establish a consistent project structure for multiple MCP servers using pre-defined templates, facade patterns, and automated scaffolding.
- Schema Refinement: Leverage the integrated web editor to fine-tune tool descriptions and input parameters, ensuring high-quality and reliable interactions between the LLM and the underlying code.
| name | mcp-setup |
|---|---|
| description | >- |
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 tomcp_demo/. - Drop a facade file (
service.pyordemo_service.py) usingreferences/service_facade_template.pyand add@mcp_serviceto each exported function. - Seed
mcp_editor/mcp_demo/tool_definition_templates.pyfromreferences/tool_definition_templates_sample.pyso the web editor has defaults. - Add a
mcp_demoprofile block tomcp_editor/editor_config.json(seereferences/editor_config_snippet.json). - Run
python mcp_editor/tool_editor_web.py, verify auto-scan picked up the decorators, adjust schemas, then Save to emittool_definitions.py. - Generate the server when ready:
python jinja/generate_universal_server.py demo(do not hand-edit generated files).
Workflow
- Prepare the target project
- Normalize naming: folders and editor config keys should be
mcp_{server}. Place server code undermcp_{server}/mcp_server/. - Keep business logic importable by the facade (no heavy side effects on import; move those behind functions).
- 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.
- Build the facade with decorators
- Start from
references/service_facade_template.py; copy tomcp_{server}/{server}_service.py(orservice.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.pyand import them. - Prefer pure wrappers so scanning stays stable; avoid doing I/O at module import time.
- Register services
- Launch the web editor (
python mcp_editor/tool_editor_web.py) to auto-scan@mcp_serviceand refreshregistry_{server}.json, or runpython mcp_editor/mcp_service_registry/mcp_service_scanner.pydirectly. - Confirm the registry entry shows
tool_name,server_name, and the correct implementation module/method.
- Seed tool templates (LLM-facing schemas)
- Copy
references/tool_definition_templates_sample.pytomcp_editor/mcp_{server}/tool_definition_templates.pyand align entries with your decorated functions. - Use
mcp_editor/mcp_service_registry/mcp_service_decorator.generate_inputschema_from_serviceif you want to auto-derive a startinginputSchemafrom the captured signature; then refine descriptions and required fields. - Keep
MCP_TOOLSin sync with the facade: names, signatures, and targetParam mappings should mirror the@mcp_serviceparameters. Include at least one default entry so the editor UI is not empty.
- Wire the web editor profile
- Add a profile block in
mcp_editor/editor_config.jsonkeyed bymcp_{server}: template path, output path, optionaltypes_files, and port/host. Usereferences/editor_config_snippet.jsonas a shape guide. - If you prefer templating, regenerate via
python jinja/generate_editor_config.pyafter editing the template.
- 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 generatedserver.pyortool_definitions.pydirectly; modify templates/facades instead. - Smoke test:
python mcp_{server}/mcp_server/server.pythen 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
descriptionfrom docstrings/comments. - Always add a couple of safe defaults (health/ping, list/sample) in
tool_definition_templates.pyso 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 formcp_{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.pyfor decorator details.