mcpsmith 0.1.0__tar.gz

mcpsmith-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "mcpsmith",
+  "description": "Build curated, tested MCP servers from an OpenAPI file or a recorded website session.",
+  "owner": {
+    "name": "Sepehr Radmard",
+    "email": "sepehrr80@gmail.com",
+    "url": "https://github.com/sepehr071"
+  },
+  "plugins": [
+    {
+      "name": "mcpsmith",
+      "source": "./",
+      "description": "Skills and an MCP server that guide your coding agent from an OpenAPI file or HAR to a tested MCP server project.",
+      "category": "development"
+    }
+  ]
+}

mcpsmith-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "mcpsmith",
+  "displayName": "mcpsmith",
+  "version": "0.1.0",
+  "description": "Turn an OpenAPI file or a recorded website session into a curated, tested MCP server. Skills and an MCP server for your coding agent.",
+  "author": {
+    "name": "Sepehr Radmard",
+    "email": "sepehrr80@gmail.com",
+    "url": "https://github.com/sepehr071"
+  },
+  "homepage": "https://github.com/sepehr071/mcpsmith",
+  "repository": "https://github.com/sepehr071/mcpsmith",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "openapi",
+    "har",
+    "code-generation",
+    "mcp-server",
+    "agents"
+  ],
+  "mcpServers": {
+    "mcpsmith": {
+      "command": "uvx",
+      "args": [
+        "mcpsmith@0.1.0",
+        "mcp"
+      ]
+    }
+  }
+}

mcpsmith-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q

mcpsmith-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
+# pyproject.toml and server.json.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+      contents: write  # GitHub Release
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Check versions match the tag
+        run: |
+          TAG=${GITHUB_REF_NAME#v}
+          grep -q "^version = \"$TAG\"" pyproject.toml
+          test "$(jq -r .version server.json)" = "$TAG"
+          test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
+      - run: uv sync --locked && uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # MCP Registry login via GitHub OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Wait for PyPI to serve the new version
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf "https://pypi.org/pypi/mcpsmith/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
+            sleep 10
+          done
+          exit 1
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

mcpsmith-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mcpsmith/
+*.har
+!tests/fixtures/har/*.har

mcpsmith-0.1.0/AGENTS.md

@@ -0,0 +1,49 @@
+# mcpsmith
+
+Python framework that turns an OpenAPI/Swagger file or a recorded website session (HAR) into a curated, tested MCP server project. An LLM designs the tools: you (the coding agent) edit `plan.yaml`, or `mcpsmith design --provider ...` calls an LLM API. Generated projects use `mcpsmith.runtime` and include tests, CI, a PyPI/MCP Registry publish workflow, `server.json` and a Claude Code plugin.
+
+## Workflow
+
+Ask the user which tasks the server should support, then:
+
+1. Website only: `mcpsmith capture <url> -o site.har --host <host>` (user browses, closes the browser), or use a DevTools HAR export.
+2. `mcpsmith inspect <openapi-or-har path|url>` writes `.mcpsmith/source.json` and `.mcpsmith/digest.md`.
+3. Read `.mcpsmith/digest.md` and the output of `mcpsmith guide` (tool-design rules).
+4. `mcpsmith draft` writes a heuristic `.mcpsmith/plan.yaml`.
+5. Redesign `plan.yaml` yourself: merge or drop endpoints, plain arg names, one-sentence first lines, compact `output.fields`, `example` per tool, `instructions`.
+6. `mcpsmith validate` (exit 1 on errors).
+7. `mcpsmith generate -o <dir>`, then `cd <dir> && uv run pytest`.
+8. `mcpsmith check <dir>` calls every tool live: errors, output size, empty fields. Confirm with the user before it runs non-GET tools.
+9. Edit the plan and `generate --force` to iterate. Hand edits to `server.py` are overwritten by regenerating.
+10. Publish: PyPI trusted publisher (workflow `publish.yml`, environment `pypi`), bump `version` in `pyproject.toml` and `server.json`, tag `v*`.
+
+Without a shell, use the MCP tools below (`smith_guide`, `smith_inspect`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check`; paths absolute).
+
+## Skills
+
+- `skills/build-mcp-server/SKILL.md`: the full workflow above.
+- `skills/design-mcp-tools/SKILL.md`: checklist for designing or reviewing tools, and how to measure output size.
+
+Codex, Cursor, Gemini CLI and others: read these files directly; they are plain Markdown.
+
+## MCP server config
+
+```json
+{"mcpServers": {"mcpsmith": {"command": "uvx", "args": ["mcpsmith", "mcp"]}}}
+```
+
+Claude Code: `claude mcp add mcpsmith -- uvx mcpsmith mcp`, or `/plugin marketplace add sepehr071/mcpsmith` then `/plugin install mcpsmith@mcpsmith`.
+
+## Contributing
+
+```
+uv sync
+uv run pytest            # live tests are skipped; run them with -m live
+uv run ruff check .
+uv run ruff format .
+```
+
+- Layout: `src/mcpsmith/` (`model.py` is the data contract: `Source`, `Plan`; `importers/`, `design/`, `codegen/`, `runtime/`, `check.py`, `cli.py`); design notes in `docs/design.md`.
+- Do not rename `model.py` fields without checking every stage that reads them.
+- `mcpsmith.runtime` is imported by every generated server: keep it small and backward compatible.
+- Ruff: line length 120, Python 3.10+.

mcpsmith-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sepehr Radmard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcpsmith-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: mcpsmith
+Version: 0.1.0
+Summary: Turn an OpenAPI file or a recorded website session into a curated, tested MCP server, with an LLM designing the tools.
+Project-URL: Homepage, https://github.com/sepehr071/mcpsmith
+Project-URL: Issues, https://github.com/sepehr071/mcpsmith/issues
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,code-generation,har,llm,mcp,model-context-protocol,openapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: pyyaml>=6
+Provides-Extra: capture
+Requires-Dist: playwright>=1.45; extra == 'capture'
+Provides-Extra: stealth
+Requires-Dist: curl-cffi>=0.16.3; extra == 'stealth'
+Requires-Dist: httpx-curl-cffi>=0.1.5; extra == 'stealth'
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.sepehr071/mcpsmith -->
+
+# mcpsmith
+
+Turn an OpenAPI/Swagger file, or a website session you recorded in the browser, into a curated, tested MCP server project. An LLM designs the tools; you get ordinary Python code you own.
+
+Most generators mirror every endpoint as a tool and hand the model raw JSON, or stop at an OpenAPI spec or API client. mcpsmith designs a few workflow-level tools with plain argument names, descriptions that say when to call what next, and compact output. The input is an OpenAPI file or a HAR recording, so sites with no public API work too. The output is a server project with tests, CI, a PyPI + MCP Registry publish workflow and a Claude Code plugin.
+
+## Quickstart: OpenAPI
+
+```bash
+uvx mcpsmith inspect https://petstore3.swagger.io/api/v3/openapi.json   # .mcpsmith/source.json + digest.md
+uvx mcpsmith draft --name petstore-mcp                                  # heuristic .mcpsmith/plan.yaml, no LLM
+# redesign plan.yaml (your coding agent does this, or use `design`, see below)
+uvx mcpsmith validate
+uvx mcpsmith generate -o petstore-mcp
+cd petstore-mcp && uv run pytest
+uvx mcpsmith check .                                                    # call every tool live
+claude mcp add petstore-mcp -- uv run --directory "$PWD" petstore-mcp
+```
+
+A spec read from a local file may only have a relative server URL; `validate` then asks you to set an absolute `base_url` in the plan.
+
+## Quickstart: a website without an API
+
+```bash
+pip install "mcpsmith[capture]" && playwright install chromium
+mcpsmith capture https://example.com -o site.har --host example.com   # browse, then close the tab
+mcpsmith inspect site.har --host example.com
+mcpsmith draft --name example-mcp
+# redesign plan.yaml, then validate, generate, check as above
+```
+
+While recording, do each thing you want as a tool: search, open a detail page, paginate, apply a filter. Anything you do not click is not in the capture. `--host` (repeatable) keeps only the hosts you list. A DevTools "Save all as HAR" export works in place of `capture`. The recording browser uses `HTTPS_PROXY` when it is set.
+
+A HAR holds everything the browser sent and received, including cookies and your personal data: keep it out of git and delete it after `inspect`. `inspect` scrubs what it keeps: an API key or token becomes an `auth` env var with its value dropped, other secret-looking headers and query params are dropped, and emails, phone numbers, JWTs and values under secret or personal field names are masked in examples and test fixtures. This is pattern-based, so read `tests/fixtures/` before you publish a generated server. If a key is a public one the site sends to every visitor (a search or maps key), you may put it in the tool's `fixed` values.
+
+## Use it from your agent
+
+No API key needed: your coding agent is the designer.
+
+- Claude Code plugin (skills + MCP server): `/plugin marketplace add sepehr071/mcpsmith`, then `/plugin install mcpsmith@mcpsmith`.
+- MCP server only, any client:
+  ```json
+  {"mcpServers": {"mcpsmith": {"command": "uvx", "args": ["mcpsmith", "mcp"]}}}
+  ```
+  Tools: `smith_guide`, `smith_inspect`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check` (paths absolute).
+- Skills: `skills/build-mcp-server` (the whole workflow) and `skills/design-mcp-tools` (design checklist). `AGENTS.md` points other agents (Codex, Cursor, Gemini CLI) at them.
+
+Then ask: "Build an MCP server for this OpenAPI file; users should be able to find pets and check stock."
+
+## Let mcpsmith call an LLM
+
+```bash
+uvx mcpsmith design --goal "find products, compare prices, read reviews" --provider anthropic
+```
+
+Providers: `anthropic` (`ANTHROPIC_API_KEY`), `openai` (`OPENAI_API_KEY`), `openrouter` (`OPENROUTER_API_KEY`), `ollama` (no key). `--model` picks the model; `MCPSMITH_MODEL` and `MCPSMITH_BASE_URL` override the model and endpoint. The result is the same `plan.yaml`; review it before `generate`.
+
+## How it works
+
+```
+openapi.yaml | site.har --inspect--> source.json + digest.md
+                        --draft----> plan.yaml     (heuristic starting point)
+   your agent edits plan.yaml, or `design` ------> plan.yaml
+                        --validate-> issues
+                        --generate-> <name>/       (server project)
+                        --check----> live report per tool
+```
+
+`Source` is what the API offers; `Plan` is the server to build; code generation reads the plan plus captured responses for test fixtures. A plan, trimmed:
+
+```yaml
+name: shop-mcp
+description: Search products and compare prices on Example Shop.
+prefix: shop
+base_url: https://example.com/api
+env_prefix: SHOP_MCP
+instructions: Search first, then fetch details with the id. Prices are in toman.
+tools:
+  - name: shop_search
+    title: Search products
+    description: Returns matching products with price and stock. Use shop_product for full details.
+    endpoint: GET /v2/search
+    args:
+      - {name: query, type: string, required: true, description: "Search words, e.g. 'laptop'", to: query.q}
+      - {name: max_price, type: integer, description: "Upper price limit in toman, e.g. 20000000", to: query.price_max}
+      - {name: sort, description: "Result order.", map: {cheapest: price_asc, newest: date_desc}, default: cheapest, to: query.o}
+    output:
+      root: data.products
+      fields: {id: id, title: title_fa, price: price.selling_price, in_stock: stock.available}
+      max_items: 10
+    example: {query: laptop}
+```
+
+Argument targets (`to:`): `path.<n>`, `query.<n>`, `header.<n>`, `cookie.<n>`, `body`, `body.<a.b.c>`. Output paths use dots, a number indexes a list (`images.0.url`), `[]` maps over a list (`tags[].name`). `map` turns friendly values the model sees into the cryptic ones the API wants.
+
+## What you get
+
+```
+<name>/
+  pyproject.toml  server.json  README.md  LICENSE  .gitignore  mcpsmith.yaml
+  src/<package>/server.py        # tools, built on mcpsmith.runtime
+  tests/                         # replay captured responses; one -m live test per tool
+  .github/workflows/             # ci.yml, publish.yml (PyPI + MCP Registry)
+  .claude-plugin/plugin.json     # Claude Code plugin
+  skills/<name>/SKILL.md         # skill for the generated server
+```
+
+`mcpsmith.yaml` is the plan, so you can regenerate. To publish: add a PyPI trusted publisher (workflow `publish.yml`, environment `pypi`), bump the version in `pyproject.toml` and `server.json`, tag `v*`.
+
+## Runtime features
+
+Generated servers import `mcpsmith.runtime`, so a fix there reaches every server on upgrade.
+
+- Retries on network errors, timeouts, 429 and 5xx (writes only on 429, so they are never sent twice); `Retry-After` honoured and capped; jitter; concurrency cap.
+- GET response cache, host allowlist, 5 MB body cap.
+- Proxy support: `<P>_PROXY` takes one URL or a comma list (pool). `<P>_BASE_URL` overrides the base URL. System proxy env vars are ignored on purpose.
+- Chrome TLS fingerprint for sites that block plain clients: `pip install "mcpsmith[stealth]"` and `impersonate: true` in the plan. Without the extra it falls back to plain httpx with one warning.
+- Compact output: `shape()` keeps only the planned fields, caps lists (reports the total count), clips long strings, drops nulls.
+- Actionable errors: a 403 suggests setting `<P>_PROXY`, a 401 names the auth env var, 404/429/5xx say what to do next.
+- Auth: bearer, header, query, cookie or basic, read from an env var.
+
+## Drift check
+
+`mcpsmith check <project> [--json]` calls every tool with its example arguments and reports errors, output size in characters and output fields that came back empty. Run it nightly in CI to see when an API or site changes. It makes real calls, so tools marked `read_only: false` are skipped unless you pass `--writes`.
+
+## Comparison
+
+| | Input | Output | Tool design | Response shaping | Drift check | Open source |
+|---|---|---|---|---|---|---|
+| mcpsmith | OpenAPI, HAR | Python MCP project | LLM-designed plan | per-tool root/fields/max_items | `mcpsmith check` | yes |
+| FastMCP `from_openapi` | OpenAPI | runtime proxy | one tool per endpoint; manual route maps / transforms | raw JSON | no | yes |
+| openapi-mcp-generator | OpenAPI | TypeScript server | one tool per endpoint; `x-mcp` to pick | raw JSON | no | yes |
+| Speakeasy / Gram | OpenAPI | TypeScript or hosted | manual toolsets | experimental | no | Gram yes |
+| Stainless | OpenAPI | npm package | code mode (search + execute) | n/a | no | no |
+| mitmproxy2swagger, har-to-openapi | HAR / traffic | OpenAPI spec | none | none | no | yes |
+| Integuru, reverse-api-engineer | HAR / browsing | API client code, not MCP | none | none | no | yes |
+| Supergood, Wire | site walkthrough | hosted API / MCP | managed | managed | vendor claims | no |
+
+Compiled from each project's public docs in October 2026; check them before relying on a cell. FastMCP's own docs say curated servers clearly beat auto-converted ones.
+
+## Limitations
+
+- No browser per call: JS challenges and captchas are out of scope. Sites that need them will fail at `check`.
+- A tool maps to one request. Multi-call workflow tools need hand edits to the generated `server.py`, and regenerating overwrites them.
+- The generated project is Python only.
+- A HAR only contains what you did while recording; unrecorded features are not in the plan.
+- Request bodies are sent as JSON; endpoints that only accept `application/x-www-form-urlencoded` or multipart need a hand edit.
+- The plan is trusted input: its text ends up in server instructions and the skill, and `mcpsmith check` runs the generated code. Review a plan written by an LLM from third-party content before you generate and publish it.
+- Alpha (0.1).
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT

mcpsmith-0.1.0/README.md

@@ -0,0 +1,163 @@
+<!-- mcp-name: io.github.sepehr071/mcpsmith -->
+
+# mcpsmith
+
+Turn an OpenAPI/Swagger file, or a website session you recorded in the browser, into a curated, tested MCP server project. An LLM designs the tools; you get ordinary Python code you own.
+
+Most generators mirror every endpoint as a tool and hand the model raw JSON, or stop at an OpenAPI spec or API client. mcpsmith designs a few workflow-level tools with plain argument names, descriptions that say when to call what next, and compact output. The input is an OpenAPI file or a HAR recording, so sites with no public API work too. The output is a server project with tests, CI, a PyPI + MCP Registry publish workflow and a Claude Code plugin.
+
+## Quickstart: OpenAPI
+
+```bash
+uvx mcpsmith inspect https://petstore3.swagger.io/api/v3/openapi.json   # .mcpsmith/source.json + digest.md
+uvx mcpsmith draft --name petstore-mcp                                  # heuristic .mcpsmith/plan.yaml, no LLM
+# redesign plan.yaml (your coding agent does this, or use `design`, see below)
+uvx mcpsmith validate
+uvx mcpsmith generate -o petstore-mcp
+cd petstore-mcp && uv run pytest
+uvx mcpsmith check .                                                    # call every tool live
+claude mcp add petstore-mcp -- uv run --directory "$PWD" petstore-mcp
+```
+
+A spec read from a local file may only have a relative server URL; `validate` then asks you to set an absolute `base_url` in the plan.
+
+## Quickstart: a website without an API
+
+```bash
+pip install "mcpsmith[capture]" && playwright install chromium
+mcpsmith capture https://example.com -o site.har --host example.com   # browse, then close the tab
+mcpsmith inspect site.har --host example.com
+mcpsmith draft --name example-mcp
+# redesign plan.yaml, then validate, generate, check as above
+```
+
+While recording, do each thing you want as a tool: search, open a detail page, paginate, apply a filter. Anything you do not click is not in the capture. `--host` (repeatable) keeps only the hosts you list. A DevTools "Save all as HAR" export works in place of `capture`. The recording browser uses `HTTPS_PROXY` when it is set.
+
+A HAR holds everything the browser sent and received, including cookies and your personal data: keep it out of git and delete it after `inspect`. `inspect` scrubs what it keeps: an API key or token becomes an `auth` env var with its value dropped, other secret-looking headers and query params are dropped, and emails, phone numbers, JWTs and values under secret or personal field names are masked in examples and test fixtures. This is pattern-based, so read `tests/fixtures/` before you publish a generated server. If a key is a public one the site sends to every visitor (a search or maps key), you may put it in the tool's `fixed` values.
+
+## Use it from your agent
+
+No API key needed: your coding agent is the designer.
+
+- Claude Code plugin (skills + MCP server): `/plugin marketplace add sepehr071/mcpsmith`, then `/plugin install mcpsmith@mcpsmith`.
+- MCP server only, any client:
+  ```json
+  {"mcpServers": {"mcpsmith": {"command": "uvx", "args": ["mcpsmith", "mcp"]}}}
+  ```
+  Tools: `smith_guide`, `smith_inspect`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check` (paths absolute).
+- Skills: `skills/build-mcp-server` (the whole workflow) and `skills/design-mcp-tools` (design checklist). `AGENTS.md` points other agents (Codex, Cursor, Gemini CLI) at them.
+
+Then ask: "Build an MCP server for this OpenAPI file; users should be able to find pets and check stock."
+
+## Let mcpsmith call an LLM
+
+```bash
+uvx mcpsmith design --goal "find products, compare prices, read reviews" --provider anthropic
+```
+
+Providers: `anthropic` (`ANTHROPIC_API_KEY`), `openai` (`OPENAI_API_KEY`), `openrouter` (`OPENROUTER_API_KEY`), `ollama` (no key). `--model` picks the model; `MCPSMITH_MODEL` and `MCPSMITH_BASE_URL` override the model and endpoint. The result is the same `plan.yaml`; review it before `generate`.
+
+## How it works
+
+```
+openapi.yaml | site.har --inspect--> source.json + digest.md
+                        --draft----> plan.yaml     (heuristic starting point)
+   your agent edits plan.yaml, or `design` ------> plan.yaml
+                        --validate-> issues
+                        --generate-> <name>/       (server project)
+                        --check----> live report per tool
+```
+
+`Source` is what the API offers; `Plan` is the server to build; code generation reads the plan plus captured responses for test fixtures. A plan, trimmed:
+
+```yaml
+name: shop-mcp
+description: Search products and compare prices on Example Shop.
+prefix: shop
+base_url: https://example.com/api
+env_prefix: SHOP_MCP
+instructions: Search first, then fetch details with the id. Prices are in toman.
+tools:
+  - name: shop_search
+    title: Search products
+    description: Returns matching products with price and stock. Use shop_product for full details.
+    endpoint: GET /v2/search
+    args:
+      - {name: query, type: string, required: true, description: "Search words, e.g. 'laptop'", to: query.q}
+      - {name: max_price, type: integer, description: "Upper price limit in toman, e.g. 20000000", to: query.price_max}
+      - {name: sort, description: "Result order.", map: {cheapest: price_asc, newest: date_desc}, default: cheapest, to: query.o}
+    output:
+      root: data.products
+      fields: {id: id, title: title_fa, price: price.selling_price, in_stock: stock.available}
+      max_items: 10
+    example: {query: laptop}
+```
+
+Argument targets (`to:`): `path.<n>`, `query.<n>`, `header.<n>`, `cookie.<n>`, `body`, `body.<a.b.c>`. Output paths use dots, a number indexes a list (`images.0.url`), `[]` maps over a list (`tags[].name`). `map` turns friendly values the model sees into the cryptic ones the API wants.
+
+## What you get
+
+```
+<name>/
+  pyproject.toml  server.json  README.md  LICENSE  .gitignore  mcpsmith.yaml
+  src/<package>/server.py        # tools, built on mcpsmith.runtime
+  tests/                         # replay captured responses; one -m live test per tool
+  .github/workflows/             # ci.yml, publish.yml (PyPI + MCP Registry)
+  .claude-plugin/plugin.json     # Claude Code plugin
+  skills/<name>/SKILL.md         # skill for the generated server
+```
+
+`mcpsmith.yaml` is the plan, so you can regenerate. To publish: add a PyPI trusted publisher (workflow `publish.yml`, environment `pypi`), bump the version in `pyproject.toml` and `server.json`, tag `v*`.
+
+## Runtime features
+
+Generated servers import `mcpsmith.runtime`, so a fix there reaches every server on upgrade.
+
+- Retries on network errors, timeouts, 429 and 5xx (writes only on 429, so they are never sent twice); `Retry-After` honoured and capped; jitter; concurrency cap.
+- GET response cache, host allowlist, 5 MB body cap.
+- Proxy support: `<P>_PROXY` takes one URL or a comma list (pool). `<P>_BASE_URL` overrides the base URL. System proxy env vars are ignored on purpose.
+- Chrome TLS fingerprint for sites that block plain clients: `pip install "mcpsmith[stealth]"` and `impersonate: true` in the plan. Without the extra it falls back to plain httpx with one warning.
+- Compact output: `shape()` keeps only the planned fields, caps lists (reports the total count), clips long strings, drops nulls.
+- Actionable errors: a 403 suggests setting `<P>_PROXY`, a 401 names the auth env var, 404/429/5xx say what to do next.
+- Auth: bearer, header, query, cookie or basic, read from an env var.
+
+## Drift check
+
+`mcpsmith check <project> [--json]` calls every tool with its example arguments and reports errors, output size in characters and output fields that came back empty. Run it nightly in CI to see when an API or site changes. It makes real calls, so tools marked `read_only: false` are skipped unless you pass `--writes`.
+
+## Comparison
+
+| | Input | Output | Tool design | Response shaping | Drift check | Open source |
+|---|---|---|---|---|---|---|
+| mcpsmith | OpenAPI, HAR | Python MCP project | LLM-designed plan | per-tool root/fields/max_items | `mcpsmith check` | yes |
+| FastMCP `from_openapi` | OpenAPI | runtime proxy | one tool per endpoint; manual route maps / transforms | raw JSON | no | yes |
+| openapi-mcp-generator | OpenAPI | TypeScript server | one tool per endpoint; `x-mcp` to pick | raw JSON | no | yes |
+| Speakeasy / Gram | OpenAPI | TypeScript or hosted | manual toolsets | experimental | no | Gram yes |
+| Stainless | OpenAPI | npm package | code mode (search + execute) | n/a | no | no |
+| mitmproxy2swagger, har-to-openapi | HAR / traffic | OpenAPI spec | none | none | no | yes |
+| Integuru, reverse-api-engineer | HAR / browsing | API client code, not MCP | none | none | no | yes |
+| Supergood, Wire | site walkthrough | hosted API / MCP | managed | managed | vendor claims | no |
+
+Compiled from each project's public docs in October 2026; check them before relying on a cell. FastMCP's own docs say curated servers clearly beat auto-converted ones.
+
+## Limitations
+
+- No browser per call: JS challenges and captchas are out of scope. Sites that need them will fail at `check`.
+- A tool maps to one request. Multi-call workflow tools need hand edits to the generated `server.py`, and regenerating overwrites them.
+- The generated project is Python only.
+- A HAR only contains what you did while recording; unrecorded features are not in the plan.
+- Request bodies are sent as JSON; endpoints that only accept `application/x-www-form-urlencoded` or multipart need a hand edit.
+- The plan is trusted input: its text ends up in server instructions and the skill, and `mcpsmith check` runs the generated code. Review a plan written by an LLM from third-party content before you generate and publish it.
+- Alpha (0.1).
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT