# skill-to-mcp - Model Context Protocol Server Generator (`opportunity-biz/skill-to-mcp`) Actor Turn plain-English tool descriptions into complete Model Context Protocol MCP servers. AI infers JSON Schema, generates Pydantic v2 models, handler code, stdio/SSE transport. Works with Claude Desktop, Cursor, MCP hosts. 3 free runs! - **URL**: https://apify.com/opportunity-biz/skill-to-mcp.md - **Developed by:** [opportunity-biz](https://apify.com/opportunity-biz) (community) - **Categories:** MCP servers, AI, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## skill-to-mcp > **Turn a plain-English skill description into a working MCP server in seconds.** [![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-136%20passed-brightgreen)](tests/) [![PyPI version](https://img.shields.io/pypi/v/skillmd-to-mcp)](https://pypi.org/project/skillmd-to-mcp/) [![Python Versions](https://img.shields.io/pypi/pyversions/skillmd-to-mcp)](https://pypi.org/project/skillmd-to-mcp/) [![PyPI Downloads](https://img.shields.io/pypi/dm/skillmd-to-mcp)](https://pypi.org/project/skillmd-to-mcp/) [![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](tests/) ![skill-to-mcp demo](demo/demo.gif) **`skill-to-mcp`** is a CLI code generator that reads a `SKILL.md` file — a plain-English description of a tool — and scaffolds a complete, runnable **MCP (Model Context Protocol) server** with: - ✅ Correct JSON-RPC schema (`tool_name`, `description`, `inputSchema`, `outputSchema`) - ✅ Pydantic v2 models for type-safe input/output - ✅ MCP server boilerplate (stdio or HTTP SSE transport) - ✅ `pyproject.toml` ready for `pip install` - ✅ Auto-generated `README.md` with usage instructions > 📖 [Leggi in Italiano](README.it.md) --- ### Why? Describing a tool in Markdown is **more readable, versionable, and composable** than hand-writing JSON-RPC schemas. `skill-to-mcp` bridges the gap between *"I know what my tool does"* and *"I have a working MCP server."* Read the full motivation: [SKILL.md might be a better abstraction than function calling](https://reddit.com/r/ClaudeAI/comments/1ug83x6/why_skillmd_might_be_a_better_abstraction_than/) --- ### Apify Actor Run skill-to-mcp on the [Apify platform](https://apify.com/): ```bash docker build -t skill-to-mcp . docker run -e DEEPSEEK_API_KEY=sk-... skill-to-mcp ```` The Apify Actor accepts the same inputs as the CLI via a web form: **Skill Description** (required), **LLM Model**, **MCP Transport**, **Generate Example Implementation**, and **API Key**. Output is pushed to the Apify Dataset and a ZIP archive of all generated files is saved to the key-value store. The Actor builds directly from this git repository via [`.actor/actor.json`](.actor/actor.json) and the root [`Dockerfile`](Dockerfile) (entry point: `python -m skill_to_mcp.actor`). > 📖 [Apify Actor documentation](.actor/input_schema.json) *** ### Quick Start #### 1. Install ```bash pip install skillmd-to-mcp ``` #### 2. Set your API key ```bash export DEEPSEEK_API_KEY="sk-your-key-here" ``` Get a key at [platform.deepseek.com](https://platform.deepseek.com/api_keys). **Cost per generation: < $0.001** with DeepSeek. > **OpenAI fallback:** If you have an OpenAI key, set `OPENAI_API_KEY` instead. > The CLI automatically tries both: `DEEPSEEK_API_KEY` first, then `OPENAI_API_KEY`. #### 3. Create a `SKILL.md` ```markdown ## webpage-reader Fetches a web page given a URL and returns: - title: the page title - description: the meta description - body_text: visible text stripped of HTML - links: list of the first 10 internal links ### Input - url: string, required - max_links: integer, default 10 ``` #### 4. Generate the MCP server ```bash skill-to-mcp generate SKILL.md ``` **Output:** ``` output/ └── webpage-reader/ ├── server.py # MCP server, runnable immediately ├── models.py # Pydantic v2 input/output models ├── handler.py # Tool logic (stub — implement here) ├── pyproject.toml # Dependencies and metadata └── README.md # Installation and usage guide ``` #### 5. Implement & Run ```bash cd output/webpage-reader pip install -e . ## Edit handler.py to add your business logic python server.py ``` *** ### CLI Reference ``` skill-to-mcp generate SKILL.md [OPTIONS] ``` #### Arguments | Argument | Description | |----------|-------------| | `SKILL.md` | Path to the skill description file | #### Options | Option | Short | Default | Description | |--------|-------|---------|-------------| | `--output-dir` | `-o` | `./output` | Output directory for generated files | | `--model` | `-m` | `deepseek-v4-flash` | LLM model for schema inference | | `--api-key` | `-k` | `$DEEPSEEK_API_KEY` or `$OPENAI_API_KEY` | API key for the LLM provider. Falls back to `OPENAI_API_KEY` if `DEEPSEEK_API_KEY` is not set | | `--transport` | `-t` | `stdio` | MCP transport: `stdio` or `sse` | | `--dry-run` | | `false` | Show inferred schema without generating files | | `--prompt-file` | `-p` | | Custom system prompt for LLM inference | | `--with-example-impl` | | `false` | Generate a working handler implementation via LLM | | `--templates-dir` | | | Custom Jinja2 templates directory | | `--verbose` | `-v` | `false` | Enable debug logging | #### Batch Processing Process multiple `SKILL.md` files at once: ```bash skill-to-mcp generate tool1.md tool2.md tool3.md -o ./my-tools skill-to-mcp generate *.md --with-example-impl ``` #### Examples ```bash ## Basic usage skill-to-mcp generate SKILL.md ## Preview the inferred schema (no files written) skill-to-mcp generate SKILL.md --dry-run ## Use SSE transport for HTTP-based MCP hosts skill-to-mcp generate SKILL.md --transport sse ## Custom output directory skill-to-mcp generate SKILL.md -o ./my-mcp-tools ## Use a specific model skill-to-mcp generate SKILL.md -m deepseek-v4-flash ## Custom LLM prompt skill-to-mcp generate SKILL.md --prompt-file my_prompt.txt ## Verbose output for debugging skill-to-mcp generate SKILL.md -v ``` *** ### Architecture ```mermaid flowchart LR A[SKILL.md] --> B[parser.py] B --> C[llm.py] C --> D[DeepSeek API] D --> E[validator.py] E -->|valid| F[renderer.py] E -->|invalid + retry| C F --> G[templates/] G --> H[output/] ``` #### Pipeline 1. **[`parser.py`](skill_to_mcp/parser.py)** — Reads `SKILL.md`, extracts title and sections 2. **[`llm.py`](skill_to_mcp/llm.py)** — Calls DeepSeek API (OpenAI-compatible) to infer JSON Schema 3. **[`validator.py`](skill_to_mcp/validator.py)** — Validates schema (types, snake\_case, required fields) 4. **[`renderer.py`](skill_to_mcp/renderer.py)** — Applies Jinja2 templates to generate Python code 5. **[`cli.py`](skill_to_mcp/cli.py)** — Typer-based CLI with Rich output #### LLM Prompt The system prompt is **transparent and overridable**. View the default in [`config.py`](skill_to_mcp/config.py) or customize with `--prompt-file`. *** ### MCP Host Configuration #### Claude Desktop Add to `claude_desktop_config.json`: ```json { "mcpServers": { "my-tool": { "command": "python", "args": ["path/to/output/my-tool/server.py"] } } } ``` #### Cursor IDE Add to `.cursor/mcp.json`: ```json { "mcpServers": { "my-tool": { "command": "python", "args": ["path/to/output/my-tool/server.py"] } } } ``` #### SSE Transport For HTTP-based MCP hosts: ```bash skill-to-mcp generate SKILL.md --transport sse cd output/my-tool && python server.py ## MCP endpoint: http://127.0.0.1:8000/sse ``` *** ### Development #### Setup ```bash git clone https://github.com/YOUR_USERNAME/skill-to-mcp cd skill-to-mcp pip install -e ".[dev]" ``` #### Run Tests ```bash ## All tests (99 total) pytest tests/ -v ## End-to-end only pytest tests/test_e2e.py -v ## With real API (requires DEEPSEEK_API_KEY) DEEPSEEK_API_KEY="sk-..." skill-to-mcp generate tests/fixtures/simple_skill.md --dry-run ``` #### Code Quality ```bash ruff check skill_to_mcp/ tests/ ``` *** ### Tech Stack | Component | Technology | |-----------|-----------| | CLI Framework | [Typer](https://typer.tiangolo.com/) | | Templates | [Jinja2](https://jinja.palletsprojects.com/) | | LLM SDK | [OpenAI Python](https://github.com/openai/openai-python) (DeepSeek-compatible) | | Validation | [Pydantic v2](https://docs.pydantic.dev/) | | MCP SDK | [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) | | Output | [Rich](https://rich.readthedocs.io/) | | Testing | [pytest](https://pytest.org/) + [pytest-mock](https://github.com/pytest-dev/pytest-mock) | | Linting | [ruff](https://github.com/astral-sh/ruff) | *** ### FAQ #### Do I need to understand MCP protocol internals? **No.** The generated server handles JSON-RPC, tool discovery, and schema validation. You only need to implement `handler.py`. #### What if the LLM produces a wrong schema? The validator catches type errors, invalid names, and missing fields. Retry is automatic (up to 3 attempts). Use `--dry-run` to preview before generating. #### Can I use OpenAI instead of DeepSeek? Yes. The CLI automatically falls back to `OPENAI_API_KEY` if `DEEPSEEK_API_KEY` is not set. ```bash export OPENAI_API_KEY="sk-..." skill-to-mcp generate SKILL.md --model gpt-4o-mini ``` Any OpenAI-compatible endpoint works (OpenAI, DeepSeek, OpenRouter, Together AI, etc.). #### What Python version do I need? Python 3.10+ for the CLI. The generated MCP servers also require Python 3.10+. #### Is this production-ready? This is an **MVP (v0.1.0)**. The generated code is correct and runnable, but you should review and test the generated handler before deploying. #### How much does each generation cost? **~$0.001 per generation** with DeepSeek V4 Flash. The prompt is ~300 tokens and the response is ~200 tokens. #### Is the --with-example-impl handler production-ready? The LLM-generated handler is a **starting point**. It may contain bugs (e.g., referencing local variables instead of `input.field`). Always review and test the generated code before deploying. The prompt has been tuned to minimize common LLM mistakes, but human review is recommended. *** ### Roadmap - \[x] `--with-example-impl` flag for LLM-generated handler implementations - \[ ] TypeScript/Go output support - \[x] Batch processing (multiple `SKILL.md` files) - \[ ] Hosted registry at `registry.skill-to-mcp.dev` - \[ ] `skill-to-mcp publish` command - \[ ] Smithery integration - \[x] Custom template directories (`--templates-dir`) *** ### Contributing Pull requests are welcome! See [`project_state.md`](project_state.md) for current status and next steps. 1. Fork the repo 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Run tests (`pytest tests/ -v`) 4. Commit your changes 5. Push and open a PR *** ### License MIT — see [LICENSE](LICENSE). *** *Built with ❤️ for MCP developers. If this saved you time, ⭐ the repo!* # Actor input Schema ## `skillText` (type: `string`): Describe your tool in plain English. What does it do? What inputs does it need? What outputs should it return? Be as specific as possible for the best results. ## `model` (type: `string`): The AI model used to infer your tool schema. DeepSeek works great and costs less than $0.001 per generation. You bring your own API key. ## `transport` (type: `string`): How will your MCP server communicate? stdio works with Claude Desktop & Cursor IDE. SSE is for HTTP-based hosts. ## `withExampleImpl` (type: `boolean`): Generate a complete, working handler implementation instead of a TODO stub. The AI will write the actual business logic for you. Great for getting started fast! ## `apiKey` (type: `string`): Your own API key (DeepSeek: platform.deepseek.com, OpenAI: platform.openai.com). Your key is never stored — each run uses it to call the LLM. Cost per generation: less than $0.001. ## Actor input object example ```json { "skillText": "# webpage-reader\n\nRead a web page from a URL and return the title, meta description, visible text, and the first 10 internal links.\n\nInput: url (string, required), max_links (integer, default 10)", "model": "deepseek-v4-flash", "transport": "stdio", "withExampleImpl": false } ``` # Actor output Schema ## `files` (type: `string`): Complete source code of the generated MCP server (server.py, models.py, handler.py, pyproject.toml, README.md). ## `zip` (type: `string`): Downloadable ZIP of all generated files, stored in the key-value store as \.zip. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "skillText": `# my-tool Fetches a URL and returns HTTP status and headers. Input: url (string, required) Output: status_code (integer), headers (object)` }; // Run the Actor and wait for it to finish const run = await client.actor("opportunity-biz/skill-to-mcp").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "skillText": """# my-tool Fetches a URL and returns HTTP status and headers. Input: url (string, required) Output: status_code (integer), headers (object)""" } # Run the Actor and wait for it to finish run = client.actor("opportunity-biz/skill-to-mcp").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "skillText": "# my-tool\\n\\nFetches a URL and returns HTTP status and headers.\\n\\nInput: url (string, required)\\nOutput: status_code (integer), headers (object)" }' | apify call opportunity-biz/skill-to-mcp --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=opportunity-biz/skill-to-mcp", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "skill-to-mcp - Model Context Protocol Server Generator", "description": "Turn plain-English tool descriptions into complete Model Context Protocol MCP servers. AI infers JSON Schema, generates Pydantic v2 models, handler code, stdio/SSE transport. Works with Claude Desktop, Cursor, MCP hosts. 3 free runs!", "version": "2.2", "x-build-id": "BtOwW9QXOPp7C90Jh" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/opportunity-biz~skill-to-mcp/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-opportunity-biz-skill-to-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/opportunity-biz~skill-to-mcp/runs": { "post": { "operationId": "runs-sync-opportunity-biz-skill-to-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/opportunity-biz~skill-to-mcp/run-sync": { "post": { "operationId": "run-sync-opportunity-biz-skill-to-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "skillText" ], "properties": { "skillText": { "title": "📝 Skill Description", "type": "string", "description": "Describe your tool in plain English. What does it do? What inputs does it need? What outputs should it return? Be as specific as possible for the best results." }, "model": { "title": "🤖 LLM Model", "enum": [ "deepseek-v4-flash", "deepseek-chat", "gpt-4o-mini" ], "type": "string", "description": "The AI model used to infer your tool schema. DeepSeek works great and costs less than $0.001 per generation. You bring your own API key.", "default": "deepseek-v4-flash" }, "transport": { "title": "🔌 MCP Transport", "enum": [ "stdio", "sse" ], "type": "string", "description": "How will your MCP server communicate? stdio works with Claude Desktop & Cursor IDE. SSE is for HTTP-based hosts.", "default": "stdio" }, "withExampleImpl": { "title": "✨ Generate Working Example Code", "type": "boolean", "description": "Generate a complete, working handler implementation instead of a TODO stub. The AI will write the actual business logic for you. Great for getting started fast!", "default": false }, "apiKey": { "title": "🔑 Your DeepSeek or OpenAI API Key", "type": "string", "description": "Your own API key (DeepSeek: platform.deepseek.com, OpenAI: platform.openai.com). Your key is never stored — each run uses it to call the LLM. Cost per generation: less than $0.001." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```