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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

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