mcpsmith

<!-- mcp-name: io.github.sepehr071/mcpsmith -->

<p align="center"><img src="docs/assets/banner.png" alt="mcpsmith" width="100%"></p>

# mcpsmith

Turn an OpenAPI file, a website you log in to, or an app you own into a few curated tools for your AI agent. An LLM designs the tools; you get ordinary Python code you own if you want to publish them.

```bash
uvx mcpsmith setup
```

## What you can turn into tools

| Source | Command |
|---|---|
| OpenAPI / Swagger file or URL | `mcpsmith inspect <file-or-url>` |
| Website or logged-in dashboard | `mcpsmith browser`, then your agent records it (`mcpsmith capture <url>` records a HAR without the hub) |
| Android app (APK you own) | `mcpsmith app-android app.apk --base-url https://api.example.com` |
| Electron / JavaScript app | `mcpsmith app-js <dir\|app.asar\|file> --base-url https://api.example.com` |
| Desktop program | `mcpsmith app-desktop` (prints the mitmproxy steps), then `mcpsmith app-desktop capture.har --host api.example.com` |

Apps and programs: only software you own or are authorized to analyze.

<p align="center"><img src="docs/assets/screenshot-help.png" alt="mcpsmith command list" width="100%"></p>
<p align="center"><em><code>mcpsmith --help</code>: the command list.</em></p>

## Quickstart: a logged-in website

```bash
uvx mcpsmith setup                  # once: registers mcpsmith + Chrome DevTools MCP with your agents
uvx mcpsmith browser                # opens the shared Chrome; log in to the site yourself
# restart your agent, then ask it:
#   "Record example.com in the shared Chrome and connect it as tools."
# the extract-api skill runs the rest: record, inspect, design, validate, connect
```

Your passwords and 2FA codes never reach the agent. Details are under [Live hub](#live-hub).

## Proven on real software

- **Tusky 29.0** (open-source Android client, Retrofit): `mcpsmith app-android` found 113 endpoints with every HTTP method resolved (48 GET, 43 POST, 11 DELETE, 8 PUT, 3 PATCH) and no unresolved notes. Minified annotation names were resolved from the app's own request-builder class, not guessed.
- **GitHub Desktop 3.6.7** (Electron): `mcpsmith app-js` found 33 endpoints with every method resolved. All 33 were traced to their original TypeScript line through the app's source maps.
- **hn.algolia.com** (public API, no login): recorded in the shared Chrome. 2 curated tools were connected through the hub and returned live results. The tools were still present after restarting the hub.
- **An internal attendance dashboard** (ASP.NET, cookie login): recorded while logged in. 2 tools answered the owner's questions. After logout the tools return a clear session-expired error.

Numbers are from runs on 2026-10-21 with mcpsmith 0.4.0. Reproduce the first two with `mcpsmith app-android` and `mcpsmith app-js` on those apps.

<p align="center"><img src="docs/assets/screenshot-app-js.png" alt="mcpsmith app-js reading an Electron app's own code" width="100%"></p>
<p align="center"><em><code>mcpsmith app-js</code> reading an Electron app's own code.</em></p>

## For coding agents

No API key needed: your coding agent is the designer.

- Skills (plain Markdown, any agent can read them): [`skills/build-mcp-server`](skills/build-mcp-server/SKILL.md) (the whole workflow), [`skills/extract-api`](skills/extract-api/SKILL.md) (logged-in sites into live tools), [`skills/design-mcp-tools`](skills/design-mcp-tools/SKILL.md) (design checklist). [`AGENTS.md`](AGENTS.md) points Codex, Cursor and Gemini CLI at them.
- MCP tools (paths absolute): `smith_guide`, `smith_inspect`, `smith_app_android`, `smith_app_js`, `smith_app_desktop`, `smith_probe`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check`, `smith_install`, and for the hub `smith_record_start`, `smith_record_stop`, `smith_connect`, `smith_disconnect`, `smith_connections`, `smith_login`, `smith_tools`, `smith_call`.
- MCP config, any client:
  ```json
  {"mcpServers": {"mcpsmith": {"command": "uvx", "args": ["mcpsmith", "mcp"]}}}
  ```
- Claude Code plugin (skills + MCP server): `/plugin marketplace add sepehr071/mcpsmith`, then `/plugin install mcpsmith@mcpsmith`.

MCP clients start servers without your shell's proxy variables. Behind a proxy, add `"env": {"HTTPS_PROXY": "http://127.0.0.1:8080"}` so `smith_inspect` can fetch specs.

## Live hub

Skip the project: connect a plan and its tools appear in your agent right away. The mcpsmith MCP server is the hub. Connections are saved under `~/.mcpsmith` (`MCPSMITH_HOME`) and load again on restart. They are personal (one machine, one user); `generate` stays the way to publish.

From the agent: `smith_inspect`, edit `plan.yaml`, `smith_validate`, then `smith_connect(workdir, name)` and call the new tools. If your client does not show tools added after start, use `smith_tools(connection)` and `smith_call(connection, tool, args)` (read-only tools only). `smith_connections` lists, `smith_disconnect(name)` removes (CLI: `mcpsmith connections`).

### Logged-in sites

For a dashboard or portal with no public API, the agent records the site's own calls while you use it. The `extract-api` skill runs the whole flow.

```bash
mcpsmith browser                                                      # shared Chrome on port 9222 (--port N, --no-proxy)
npx chrome-devtools-mcp@1.11.0 --browser-url=http://127.0.0.1:9222    # point Chrome DevTools MCP at it
```

1. Log in yourself in that Chrome window (passwords and 2FA never reach the agent).
2. The agent calls `smith_record_start(name, hosts)`, browses each feature twice with different inputs, then `smith_record_stop(name)`, which writes a HAR with cookies and tokens dropped.
3. It inspects, designs and connects the plan with `auth: {type: browser, login_path: /login}`. Calls reuse your Chrome session; when it expires the tool says to log in again.

Agents must not use DevTools `get_network_request`: it prints request headers, including cookies. `generate` refuses browser-auth plans because they only work with your Chrome; switch to token or API-key auth to publish.

### Websites without the hub

```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 under Export & publish
```

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.

### Apps and programs

Only for software you own or are authorized to analyze.

- Desktop program: `mcpsmith app-desktop` prints the steps to record its traffic with your own mitmproxy (`mitmdump --set hardump=capture.har`); `mcpsmith app-desktop capture.har --host api.example.com` imports the result. mcpsmith runs nothing for you, and certificate-pinned programs are out of scope.
- Android app: `mcpsmith app-android app.apk --base-url https://api.example.com` reads the app's Retrofit interface. It needs a decompiler: the free [`jadx`](https://github.com/skylot/jadx/releases) CLI on PATH (`scoop install extras/jadx`, `brew install jadx`), or REA's JADX jar (`REA_JADX_MCP_JAR`). Without `--class` it lists candidate classes. Before decompiling it triages the APK in about a second (zip listing and dex bytes): a Flutter or React Native app, or one without Retrofit, gets its next step right away (record its traffic, or `app-js` on a React Native JS bundle), and a known request-signing SDK names the sign-in provider to use.
- App that signs its own requests: plans use `auth: {type: signin, provider: xiaomi}` (Mi Home cloud is the first provider). The user signs in on the provider's own page through a link from the server's `<prefix>_login` tool (`smith_login` in the hub); the session goes to the OS keychain. Calling the login tool again names the account and where its data is, which catches a wrong account or region.
- Electron/JavaScript app: `mcpsmith app-js <dir|app.asar|file> --base-url ...` reads the calls in its shipped code.

Neither `app-android` nor `app-js` runs the app. The endpoints are unverified (no example response) until `mcpsmith probe` calls the GET ones live with your credentials (`--writes` for the rest, only after you agree). A method that cannot be read stays empty and `validate` refuses it.

## Setup

`uvx mcpsmith setup` registers the `mcpsmith` and `mcpsmith-chrome` (Chrome DevTools) MCP servers, and copies the skills into each coding agent it finds (Claude Code, Codex, Cursor, Gemini CLI). Options:

- `--dry-run` prints the plan and writes nothing.
- `--agents claude,codex` limits it to those agents (default: the ones found).
- `--rea` also installs REA (`rea-agents`). It is off by default: its MCP server adds about 200 tools to each agent, and mcpsmith's app path needs only plain tools such as `jadx`.
- `--no-skills` skips the skills; `--yes` skips the confirmation.
- `--remove` undoes what setup did. Entries and skill folders you made yourself are left alone. REA stays installed (you may have had it before); the comma