mcpsmith 0.2.2__tar.gz → 0.4.0__tar.gz

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "mcpsmith",
   "displayName": "mcpsmith",
-  "version": "0.2.2",
+  "version": "0.4.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",
@@ -23,7 +23,23 @@
     "mcpsmith": {
       "command": "uvx",
       "args": [
-        "mcpsmith@0.2.2",
+        "mcpsmith@0.4.0",
+        "mcp"
+      ]
+    },
+    "mcpsmith-chrome": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "chrome-devtools-mcp@1.11.0",
+        "--browser-url=http://127.0.0.1:9222"
+      ]
+    },
+    "rea": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "rea-agents@6.7.0",
         "mcp"
       ]
     }

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/AGENTS.md

@@ -4,6 +4,8 @@ Python framework that turns an OpenAPI/Swagger file or a recorded website sessio
 
 ## Workflow
 
+Install for your agents with `uvx mcpsmith setup` (`--dry-run` first).
+
 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.

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcpsmith
-Version: 0.2.2
+Version: 0.4.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
@@ -22,6 +22,7 @@ Requires-Dist: httpx>=0.27
 Requires-Dist: keyring>=25
 Requires-Dist: mcp<3,>=2.2
 Requires-Dist: pyyaml>=6
+Requires-Dist: tomlkit>=0.12
 Requires-Dist: truststore>=0.9
 Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
 Requires-Dist: websockets>=12
@@ -40,6 +41,23 @@ Turn an OpenAPI/Swagger file, or a website session you recorded in the browser,
 
 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.
 
+## Install
+
+```bash
+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), and installs REA (`rea-agents`) for them. Options:
+
+- `--dry-run` prints the plan and writes nothing.
+- `--agents claude,codex` limits it to those agents (default: the ones found).
+- `--no-rea` skips REA; `--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 command prints the line that removes it.
+
+Before setup first changes a config file, it copies the file to `*.mcpsmith.bak`. The backup is made once and not refreshed by later runs. Restart your agents afterwards. Run `mcpsmith browser` before using Chrome DevTools: it starts the shared Chrome the server connects to.
+
+Claude Code plugin users already get all three servers from the plugin and do not need `setup`.
+
 ## Quickstart: OpenAPI
 
 ```bash
@@ -67,6 +85,10 @@ mcpsmith draft --name example-mcp
 
 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 desktop program you own or are authorized to analyze: `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.
+
+An Android app or an Electron/JavaScript app you own or are authorized to analyze: `mcpsmith app-android app.apk --base-url https://api.example.com` reads the app's Retrofit interface (needs REA's JADX jar, `REA_JADX_MCP_JAR`), and `mcpsmith app-js <dir|app.asar|file> --base-url ...` reads the calls in its shipped code. Neither 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.
+
 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
@@ -78,7 +100,7 @@ No API key needed: your coding agent is the designer.
   ```json
   {"mcpServers": {"mcpsmith": {"command": "uvx", "args": ["mcpsmith", "mcp"]}}}
   ```
-  Tools: `smith_guide`, `smith_inspect`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check` (paths absolute), and for the hub `smith_record_start`, `smith_record_stop`, `smith_connect`, `smith_disconnect`, `smith_connections`, `smith_tools`, `smith_call`.
+  Tools: `smith_guide`, `smith_inspect`, `smith_app_android`, `smith_app_js`, `smith_app_desktop`, `smith_probe`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check` (paths absolute), and for the hub `smith_record_start`, `smith_record_stop`, `smith_connect`, `smith_disconnect`, `smith_connections`, `smith_tools`, `smith_call`.
   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.
 - Skills: `skills/build-mcp-server` (the whole workflow), `skills/extract-api` (logged-in sites into live tools) and `skills/design-mcp-tools` (design checklist). `AGENTS.md` points other agents (Codex, Cursor, Gemini CLI) at them.
 

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/README.md

@@ -6,6 +6,23 @@ Turn an OpenAPI/Swagger file, or a website session you recorded in the browser,
 
 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.
 
+## Install
+
+```bash
+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), and installs REA (`rea-agents`) for them. Options:
+
+- `--dry-run` prints the plan and writes nothing.
+- `--agents claude,codex` limits it to those agents (default: the ones found).
+- `--no-rea` skips REA; `--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 command prints the line that removes it.
+
+Before setup first changes a config file, it copies the file to `*.mcpsmith.bak`. The backup is made once and not refreshed by later runs. Restart your agents afterwards. Run `mcpsmith browser` before using Chrome DevTools: it starts the shared Chrome the server connects to.
+
+Claude Code plugin users already get all three servers from the plugin and do not need `setup`.
+
 ## Quickstart: OpenAPI
 
 ```bash
@@ -33,6 +50,10 @@ mcpsmith draft --name example-mcp
 
 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 desktop program you own or are authorized to analyze: `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.
+
+An Android app or an Electron/JavaScript app you own or are authorized to analyze: `mcpsmith app-android app.apk --base-url https://api.example.com` reads the app's Retrofit interface (needs REA's JADX jar, `REA_JADX_MCP_JAR`), and `mcpsmith app-js <dir|app.asar|file> --base-url ...` reads the calls in its shipped code. Neither 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.
+
 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
@@ -44,7 +65,7 @@ No API key needed: your coding agent is the designer.
   ```json
   {"mcpServers": {"mcpsmith": {"command": "uvx", "args": ["mcpsmith", "mcp"]}}}
   ```
-  Tools: `smith_guide`, `smith_inspect`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check` (paths absolute), and for the hub `smith_record_start`, `smith_record_stop`, `smith_connect`, `smith_disconnect`, `smith_connections`, `smith_tools`, `smith_call`.
+  Tools: `smith_guide`, `smith_inspect`, `smith_app_android`, `smith_app_js`, `smith_app_desktop`, `smith_probe`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check` (paths absolute), and for the hub `smith_record_start`, `smith_record_stop`, `smith_connect`, `smith_disconnect`, `smith_connections`, `smith_tools`, `smith_call`.
   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.
 - Skills: `skills/build-mcp-server` (the whole workflow), `skills/extract-api` (logged-in sites into live tools) and `skills/design-mcp-tools` (design checklist). `AGENTS.md` points other agents (Codex, Cursor, Gemini CLI) at them.
 

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/docs/design.md

@@ -60,6 +60,9 @@ openapi.yaml | site.har ──inspect──▶ .mcpsmith/source.json + digest.md
 
 `mcpsmith capture <url> -o site.har` opens a browser (Playwright, optional extra) and saves the session.
 A HAR exported from browser DevTools works the same.
+`mcpsmith app-desktop` is the same path for a desktop program: it prints the steps for the developer's own
+mitmproxy (`mitmdump --set hardump=<file>`), then imports the HAR through `inspect_source`. It never installs,
+starts or configures a proxy or certificate; certificate-pinned programs are out of scope.
 
 ## Data model
 

mcpsmith-0.4.0/docs/superpowers/plans/2026-10-21-app-path-task1.md

@@ -0,0 +1,70 @@
+# App Path, Task 1: unverified endpoints and live probing (plan 3, part 1)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Let a `Source` hold endpoints that were read from an app's own code (method, path, params, no response yet), and verify them by calling the read-only ones live, so later platform importers (Android, Electron, desktop capture) all share one verification step.
+
+**Architecture:** One new `Endpoint.verified` flag, and a `probe` module that calls GET candidates through the existing `mcpsmith.runtime.Api`, stores scrubbed example responses, and marks them verified. No new transport, no new auth path.
+
+**Tech Stack:** Existing: pydantic model, `runtime.Api`, `importers.har._scrub`, `mcp` server tools. No new dependency.
+
+**Spec:** `docs/superpowers/specs/2026-10-20-mcp-everything-design.md` (G9; decisions 6, 7, 10). Scope confirmed by the user on 2026-10-21: apps the developer owns or is authorized to analyze; nothing that defeats a protection (no certificate-pinning bypass, no DRM or licensing circumvention).
+
+## Global Constraints
+
+- `verified: bool = True` on `Endpoint`, so every existing importer and saved `source.json` keeps its current meaning.
+- Probing calls only `GET` endpoints by default; any other method requires an explicit opt-in argument and is reported as such. A probe that would send a write is skipped with a reason, never sent silently.
+- Probe responses go through `importers.har._scrub` before being stored, like recordings do (spec anti-goal: no secrets or personal data on disk).
+- Probing uses one `Api` built from the source's base URL plus the developer's own credentials (env var, keychain, or the shared Chrome session), exactly as hub tools do. No credential is created, guessed or brute-forced.
+- Rate limit: at most 2 concurrent requests and a short delay between probes (reuse `Api`'s concurrency cap and jitter); a 429 or 403 stops probing that host with a clear message.
+- Existing behaviour stays; full suite green; ruff clean; commits on `feat/app-path` without AI attribution.
+
+## Review Focus
+
+1. A probe target whose path still has unfilled `{placeholders}` → skipped with a reason, never requested with a literal brace. (Task tests.)
+2. A 403/429 → probing stops for that host and says so, instead of hammering it. (Task tests.)
+3. A probe response containing a token or an email → scrubbed before it reaches `source.json`. (Task tests.)
+4. An endpoint with `verified: false` and no response example → `draft` still produces a usable plan, and `validate` warns rather than crashing. (Task tests.)
+5. Non-GET candidates → never probed without the opt-in. (Task tests.)
+
+---
+
+### Task 1: `Endpoint.verified` + `smith_probe`
+
+**Files:**
+- Modify: `src/mcpsmith/model.py`, `src/mcpsmith/design/_digest.py` (mark unverified endpoints in the digest), `src/mcpsmith/design/_draft.py` (prefer verified endpoints; keep unverified ones usable), `src/mcpsmith/server.py` (new tool), `src/mcpsmith/cli.py` (new command)
+- Create: `src/mcpsmith/probe.py`
+- Test: `tests/test_probe.py`
+
+**Interfaces:**
+- Produces:
+  - `Endpoint.verified: bool = True` — False means "read from the app's code, not yet seen answering".
+  - `probe.run(source: Source, *, writes: bool = False, limit: int = 20, env: dict[str, str] | None = None) -> list[ProbeResult]`; `ProbeResult` dataclass: `endpoint` (id), `ok`, `status`, `error`, `chars`, `skipped_reason`.
+  - Each successful probe sets that endpoint's `response_example` (scrubbed, trimmed like the HAR importer does) and `verified = True`; the caller saves the source.
+  - CLI `mcpsmith probe [-w DIR] [--limit N] [--writes]` → one line per endpoint; exit 1 if every probe failed.
+  - MCP tool `smith_probe(workdir, limit=20, writes=False)` → `{"verified": n, "failed": n, "skipped": n, "results": [...]}`, `read_only=False` (it calls a live API), docstring saying writes need the user's confirmation.
+
+- [ ] **Step 1: Write the failing tests** in `tests/test_probe.py`, with a `Source` built in code (4 endpoints: a GET with a filled path, a GET whose path has an unfilled `{id}`, a POST, and a GET on a host that answers 429) and `Api.set_transport(httpx.MockTransport(...))`:
+```python
+async def test_probe_verifies_get_and_scrubs():
+    # GET /items -> {"items":[{"id":1,"email":"a@b.co","token":"secret123"}]}
+    results = probe.run(src)
+    ep = src.endpoint("GET /items")
+    assert ep.verified and "secret123" not in json.dumps(ep.response_example)
+    assert "a@b.co" not in json.dumps(ep.response_example)
+
+
+def test_probe_skips_unfillable_path_and_writes():
+    r = {x.endpoint: x for x in probe.run(src)}
+    assert "placeholder" in r["GET /items/{id}"].skipped_reason
+    assert "write" in r["POST /items"].skipped_reason and src.endpoint("POST /items").verified is False
+
+
+def test_probe_stops_host_on_429():
+    # first GET -> 429; the second GET on the same host is skipped, not sent
+    assert sent == 1 and "rate" in results[1].skipped_reason
+```
+- [ ] **Step 2: Run** `uv run pytest tests/test_probe.py -q` → FAIL (module missing).
+- [ ] **Step 3: Implement** `Endpoint.verified`, `probe.run`, the digest/draft touches (digest marks `unverified`; draft keeps such endpoints but their `Output.fields` stay empty when there is no example), the CLI command and the MCP tool.
+- [ ] **Step 4: Run** `uv run pytest -q` → PASS; ruff clean.
+- [ ] **Step 5: Commit** `feat: verify code-read endpoints by probing them live`.

mcpsmith-0.4.0/docs/superpowers/plans/2026-10-21-app-path-task2.md

@@ -0,0 +1,51 @@
+# App Path, Task 2: Android endpoint extractor (plan 3, part 2)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Turn the HTTP interface declarations in a decompiled Android app into a `Source` of unverified endpoints, so a developer can give their agent tools for their own account in their own (or an authorized) app.
+
+**Architecture:** REA (already installed by `mcpsmith setup`) decompiles the APK and returns Java source for a class; mcpsmith parses the Retrofit annotations in that text into `Endpoint`s with `verified: false`. Task 1's `probe` then verifies the read-only ones. No new transport and no bypass of any protection: this reads declarations the app itself ships.
+
+**Tech Stack:** Python stdlib `re`; the REA CLI (`npx -y rea-agents@6.7.0 …`) invoked through `subprocess` with injected runner for tests. No new dependency.
+
+**Spec:** `docs/superpowers/specs/2026-10-20-mcp-everything-design.md` (G9 Android bullet; "Spike results" table: 113/114 endpoints with method, path and parameter kinds correct on Tusky 29.0). User scope (2026-10-21): the developer's own or authorized app; nothing that defeats a protection.
+
+## Global Constraints
+
+- Input is a decompiled-class text (Java) plus the app's base URL, supplied by the caller. mcpsmith never downloads an app, and never ships or installs a decompiler itself; REA is the provider and must already be configured (its own `rea doctor` reports that).
+- Parser supports Retrofit's declarations only: `@GET @POST @PUT @PATCH @DELETE @HEAD @OPTIONS @HTTP(method=…, path=…, hasBody=…)` for the request line, and `@Path @Query @QueryMap @Field @FieldMap @Body @Part @PartMap @Header @HeaderMap @Url` for parameters, plus `@FormUrlEncoded`/`@Multipart` as body-encoding markers.
+- Minified annotation names (release builds rename `retrofit2.http.*`): resolve them by their retained **structure** (which annotation carries a `String value`, which marks a body, the `@HTTP`-shaped one with `method`/`path`/`hasBody`) and by cross-checking against a path-like string; when a name cannot be resolved with confidence, emit the endpoint with `method: ""` and a note rather than guessing. Never assume alphabetical ordering (the spike found that assumption held for one app and is unconfirmed elsewhere).
+- Every produced `Endpoint` has `verified: false`, `count: 0`, `response_example: None`, and `summary` set to the interface method's name (e.g. `homeTimeline`) so the digest is readable.
+- Base URL comes from the caller (apps often build it per account); if the caller gives none, `Source.base_url` is `""` and `validate` already errors until a plan sets one.
+- No secret from the app (hardcoded keys, tokens) is ever copied into the `Source`: run every string literal that becomes a param example or header value through `importers.har._scrub`.
+- Existing behaviour stays; full suite green; ruff clean; commits on `feat/app-path` without AI attribution.
+
+## Review Focus
+
+1. A method whose path is built by concatenation (`"users/" + id`) → emitted with the literal part and a note, or skipped with a reason — never a path containing `+` or a Java expression. (Tests.)
+2. A hardcoded credential in an `@Header("Authorization") String` default or a literal → never stored. (Tests.)
+3. An interface with two methods on the same path and different parameters → two endpoints, distinct ids. (Tests.)
+4. A class text that is not a Retrofit interface (no annotations) → empty endpoint list and a clear message, not a crash. (Tests.)
+5. `@HTTP(method="DELETE", hasBody=true)` → method DELETE, body marked, and it stays unverified and unprobed (write). (Tests.)
+
+---
+
+### Task 2: Retrofit parser + `smith_app_android`
+
+**Files:**
+- Create: `src/mcpsmith/importers/android.py`, `tests/test_android.py`, `tests/fixtures/android/interface.java` (hand-written, no real app code: a small interface covering every supported annotation, one concatenated path, one minified-name case, one `@HTTP`)
+- Modify: `src/mcpsmith/importers/__init__.py` (not auto-detected — exposed as its own function), `src/mcpsmith/server.py` (tool), `src/mcpsmith/cli.py` (command)
+
+**Interfaces:**
+- Produces:
+  - `android.parse_interface(java: str, base_url: str = "", title: str = "") -> Source` — endpoints from one decompiled interface.
+  - `android.rea_class_source(apk: Path, class_name: str, runner=subprocess.run) -> str` — thin wrapper that asks REA for a class's source; raises `RuntimeError` with REA's install/config hint when REA or its decompiler provider is unavailable.
+  - `android.find_api_classes(apk: Path, runner=subprocess.run) -> list[str]` — class names whose code contains a path-like string (`"api/`, `"/v1/`, …), via REA's code search.
+  - CLI `mcpsmith app-android <apk> [--class NAME] [--base-url URL] [-w DIR]`: with no `--class`, lists candidate classes and exits 0; with one, writes `source.json` + `digest.md` into the workdir and prints the next step (`mcpsmith probe`).
+  - MCP tool `smith_app_android(apk, class_name=None, base_url="", workdir=...)` → candidates, or `{"workdir", "endpoints", "unverified", "digest"}`; `read_only=False` (it runs REA); docstring: for the user's own or authorized app, and the endpoints are unverified until `smith_probe`.
+
+- [ ] **Step 1: Write the failing tests** in `tests/test_android.py` against the fixture: every annotation kind maps to the right `Param.location` (`path`/`query`/`body`/`header`) and `required`; `@FormUrlEncoded` + `@Field` → body params; the concatenated path is skipped with a reason or emitted with its literal prefix and a note (assert no `+` in any `path`); a literal `Authorization` value is absent from the Source JSON; two same-path methods give two ids; `@HTTP(method="DELETE", hasBody=true)` → `method == "DELETE"`; a class with no annotations → `endpoints == []`; every endpoint has `verified is False`.
+- [ ] **Step 2: Run** `uv run pytest tests/test_android.py -q` → FAIL.
+- [ ] **Step 3: Implement** the parser, the two REA wrappers (runner injected; never execute anything from the APK's own directory), the CLI command and the MCP tool.
+- [ ] **Step 4: Run** `uv run pytest -q` → PASS; ruff clean.
+- [ ] **Step 5: Commit** `feat(importers): read Android HTTP interfaces into a Source`.

mcpsmith-0.4.0/docs/superpowers/plans/2026-10-21-app-path-task3.md

@@ -0,0 +1,53 @@
+# App Path, Task 3: Electron / JavaScript app extractor (plan 3, part 3)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Read the HTTP calls an Electron (or any bundled JavaScript) app makes out of the app's own shipped code, as unverified endpoints, so a developer can give their agent tools for their own account in their own or an authorized app.
+
+**Architecture:** The app ships its JavaScript, and usually its original sources inside `.map` files (`sourcesContent`). mcpsmith reads those files, prefers the original sources when present, and extracts call sites of the app's own request helper (`request(method, path, …)`, `fetch(url, {method})`, `axios.get(url)`) into `Endpoint`s with `verified: false`. Task 1's `probe` verifies the read-only ones. Pure Python, no Node, no new dependency.
+
+**Tech Stack:** stdlib `json`, `re`, `struct` (asar index), `pathlib`. No parser dependency: extraction is regex over readable source; accuracy comes from Task 1's probe plus the agent's own review of the digest.
+
+**Spec:** `docs/superpowers/specs/2026-10-20-mcp-everything-design.md` (G9 Electron bullet; "Spike results": REA's own findings 0/45 on GitHub Desktop, a small AST pass 42/45 with every method correct, and the app's `.map` files carrying the original TypeScript). User scope (2026-10-21): the developer's own or authorized app; nothing that defeats a protection.
+
+## Global Constraints
+
+- Input is a path the caller gives: an app directory, an `app.asar`, or a single `.js`/`.ts`/`.map` file. mcpsmith never downloads an app and never unpacks an installer; an `.asar` is read (header + JSON index + offsets), not executed.
+- Treat every input file as untrusted data: read it, never import or run it, never resolve `require`/`import` targets, and keep output under the caller's workdir.
+- Prefer original sources: for every `.map` with `sourcesContent`, extract from those texts and record the original file name (e.g. `app/src/lib/api.ts`) in `Endpoint.summary`; fall back to the bundle text only for files with no map.
+- Minified identifiers stay as they are: an extracted param keeps its code name (`e`, `t`) and the digest marks the endpoint `UNVERIFIED`; the plan's author (the agent) renames them. Never invent a friendly name.
+- An endpoint is emitted only when its path is a literal or a template whose non-expression part is a literal (`repos/${owner}/${name}` → `repos/{owner}/{name}`); a path built by an unresolvable expression is skipped with a note. No `Endpoint.path` may contain `$`, `{` without a matching `}`, `+`, backticks or quotes.
+- Method comes from the call site only (the helper's first argument, `{method: …}`, or `axios.<verb>`); when it cannot be read, the endpoint keeps `method: ""` and a note — never guessed.
+- Any string literal that becomes a header value, query value or base URL goes through `importers.har._scrub`; userinfo is stripped from any absolute URL.
+- Every produced `Endpoint` has `verified: false`, `count: 0`, `response_example: None`; `Source.kind` is `"app"`.
+- Caps so a 200 MB app cannot hang the tool: at most 400 files, 8 MB per file read for extraction, 2000 endpoints; whatever is dropped is counted in a note.
+- Existing behaviour stays; full suite green; ruff clean; commits on `feat/app-path` without AI attribution.
+
+## Review Focus
+
+1. A `.map` whose `sourcesContent` is null or missing → fall back to the bundle, no crash. (Tests.)
+2. A path from a template literal with an expression in the middle → `{param}` placeholders, never `${…}` in the path. (Tests.)
+3. A hardcoded token in a header literal → scrubbed; an absolute URL with `user:pass@` → userinfo stripped. (Tests.)
+4. A malformed `.asar` (truncated, bad index) → clear error naming the file, nothing written. (Tests.)
+5. Two call sites with the same method and path in different files → two endpoints with distinct ids. (Tests.)
+
+---
+
+### Task 3: `importers/electron.py` + `smith_app_js`
+
+**Files:**
+- Create: `src/mcpsmith/importers/electron.py`, `tests/test_electron.py`, `tests/fixtures/electron/` (hand-written: `renderer.js` with a request-helper class, a `${}` template path, an unresolvable path, a header token, an absolute URL with userinfo; `renderer.js.map` with `sourcesContent` for one of them; a tiny valid `app.asar` built in the test, not committed as a binary)
+- Modify: `src/mcpsmith/importers/__init__.py` (exported as its own function, not auto-detected), `src/mcpsmith/cli.py`, `src/mcpsmith/server.py`
+
+**Interfaces:**
+- Produces:
+  - `electron.read_app(path: Path) -> dict[str, str]` — `{logical file name: text}` for `.js`/`.mjs`/`.cjs`/`.ts` plus the `sourcesContent` of their `.map` files, from a directory, an `.asar` or one file; raises `ValueError` naming the file on a malformed `.asar`.
+  - `electron.parse_sources(files: dict[str, str], base_url: str = "", title: str = "") -> Source`.
+  - CLI `mcpsmith app-js <path> [--base-url URL] [-w DIR]` → writes `source.json` + `digest.md`, prints `N endpoints, all unverified` and the `mcpsmith probe` next step.
+  - MCP tool `smith_app_js(path, base_url="", workdir=...)` → `{"workdir", "endpoints", "unverified", "digest"}`; `read_only=False`; docstring: reads the app's own shipped code, for the user's own or an authorized app, endpoints unverified until `smith_probe`.
+
+- [ ] **Step 1: Write the failing tests** in `tests/test_electron.py` against the fixtures: helper call sites give `(method, path)` pairs with templates turned into `{param}` placeholders; a `.map` with `sourcesContent` yields `Endpoint.summary` naming the original file; a null `sourcesContent` falls back to the bundle; the unresolvable path is absent and named in a note; no endpoint path contains `$`, backtick, quote or `+`; a header token literal and `user:pass@` are absent from `Source.model_dump_json()`; two same-path call sites in different files get distinct ids; a truncated `.asar` raises `ValueError` naming it; every endpoint has `verified is False` and `Source.kind == "app"`.
+- [ ] **Step 2: Run** `uv run pytest tests/test_electron.py -q` → FAIL.
+- [ ] **Step 3: Implement** the reader (asar index parse: 8-byte pickle header, then JSON index, then offsets), the extractor and the CLI/tool wiring.
+- [ ] **Step 4: Run** `uv run pytest -q` → PASS; ruff clean.
+- [ ] **Step 5: Commit** `feat(importers): read a JavaScript app's own HTTP calls into a Source`.

mcpsmith-0.4.0/docs/superpowers/plans/2026-10-21-app-path-task4.md

@@ -0,0 +1,48 @@
+# App Path, Task 4: desktop apps via a capture proxy (plan 3, part 4)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans.
+
+**Goal:** Let a developer turn their own (or an authorized) desktop program's API into agent tools by recording the program's own traffic through a local proxy they run, then feeding it into the existing pipeline.
+
+**Architecture:** Almost nothing new. mitmproxy (free, OSS, not bundled) writes a HAR with its built-in `hardump` option; mcpsmith's HAR importer already reads HAR. So this task is a guided command that prints the exact steps for the developer's platform, then imports the resulting HAR with the existing `inspect` path, plus the skill text that keeps an agent from doing anything the developer did not ask for.
+
+**Tech Stack:** Existing `importers.load` (HAR), `cli`, `server`. No new dependency; mitmproxy is the developer's own tool, invoked by the developer.
+
+**Spec:** `docs/superpowers/specs/2026-10-20-mcp-everything-design.md` (G9 native bullet; decision 13: native desktop apps use proxy capture because static extraction recovered ~4% of REST paths from a Go binary). User scope (2026-10-21): the developer's own or authorized software; nothing that defeats a protection.
+
+## Global Constraints
+
+- mcpsmith never installs, starts or configures a proxy, never installs a CA certificate, and never changes system or OS proxy settings. It prints the commands and the developer runs them. The guidance must say plainly that intercepting a program's traffic requires that the developer owns the program or is authorized to analyze it, and that certificate-pinned programs are out of scope (no bypass is offered or described).
+- `hardump` is mitmproxy's documented option ("Save a HAR file with all flows on exit"), used as `mitmdump --set hardump=<file>` and available in mitmproxy/mitmdump/mitmweb; the printed instructions use it, plus `--set save_stream_filter=` guidance for narrowing hosts.
+- The import path is the existing HAR importer: no second parser. `app-desktop` with a HAR delegates to the same `inspect_source` the CLI already uses, so scrubbing of secrets, cookies and personal data applies unchanged.
+- Endpoints from a capture keep the HAR importer's existing semantics (`verified: True`, real response examples) — unlike the static importers, a capture is evidence of a real answer.
+- Nothing is executed from the capture's directory; the HAR is read as untrusted data.
+- Existing behaviour stays; full suite green; ruff clean; commits on `feat/app-path` without AI attribution.
+
+## Review Focus
+
+1. The printed steps must be correct per platform (Windows/macOS/Linux) for proxy address, the certificate step and the dump flag — a wrong flag wastes the developer's session. (Test asserts the exact `--set hardump=` form and that no step tells the user to disable certificate validation.)
+2. A HAR that contains only the proxy's own CONNECT entries or no JSON → clear "nothing to import" message, not an empty `Source` written silently. (Test.)
+3. A capture of a program that is not the target (other apps' traffic on the same proxy) → `--host` filtering is offered and applied. (Test.)
+4. The guidance must not describe defeating pinning or any protection; it must say such programs are out of scope. (Test greps the skill text for the sentence.)
+5. Secrets in a desktop capture (an app token in a header) are scrubbed by the existing importer before anything is written. (Test.)
+
+---
+
+### Task 4: `app-desktop` command + skill
+
+**Files:**
+- Modify: `src/mcpsmith/cli.py`, `src/mcpsmith/server.py`, `skills/extract-api/SKILL.md` (a "desktop app" section), `README.md` (one line in the app-path list), `docs/design.md`
+- Create: `tests/test_desktop.py`
+
+**Interfaces:**
+- Produces:
+  - CLI `mcpsmith app-desktop [HAR] [--port 8080] [--host H]... [-w DIR]`: with no HAR, prints the numbered steps (run `mitmdump --set hardump=<workdir>/capture.har -p <port>`, point the program at `http://127.0.0.1:<port>` or the OS proxy for that program only, install mitmproxy's CA for the program's trust store as mitmproxy's own docs describe, use the features you want as tools, stop mitmdump) and exits 0; with a HAR, imports it through the existing `inspect_source` and prints the endpoint count and the `mcpsmith draft` next step. Refuses to overwrite an existing `source.json` without `--force`.
+  - MCP tool `smith_app_desktop(har=None, hosts=None, workdir=..., port=8080)` → either `{"steps": [...]}` or `{"workdir", "endpoints", "digest"}`; `read_only=False`; docstring states the developer runs the proxy themselves and that this is for their own or authorized software.
+- Consumes: `cli.inspect_source`, `importers.load`.
+
+- [ ] **Step 1: Write the failing tests** in `tests/test_desktop.py`: the steps text contains `--set hardump=` and the workdir path, names the port, and contains no instruction to disable TLS verification (assert the absence of "verify" / "--ssl-insecure" / "pinning bypass"); a hand-written HAR with one JSON API call and one CONNECT entry imports to one endpoint; a HAR with no JSON calls prints "nothing to import" and writes no `source.json`; `--host` keeps only the named host; an `Authorization` header value in the HAR is absent from the written `source.json`; the skill text contains the out-of-scope sentence about certificate-pinned programs.
+- [ ] **Step 2: Run** `uv run pytest tests/test_desktop.py -q` → FAIL.
+- [ ] **Step 3: Implement** the command, the tool, and the skill/README/design wording.
+- [ ] **Step 4: Run** `uv run pytest -q` → PASS; ruff clean; `claude plugin validate .` passes.
+- [ ] **Step 5: Commit** `feat: import a desktop app's own traffic from a developer-run proxy`.

mcpsmith-0.4.0/docs/superpowers/plans/2026-10-21-setup-bundle.md

@@ -0,0 +1,75 @@
+# Setup Bundle Implementation Plan (plan 2 of 3)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `mcpsmith setup` registers the mcpsmith hub, Chrome DevTools MCP (attached to the shared Chrome) and REA with Claude Code, Codex, Cursor and Gemini CLI, and installs mcpsmith's skills — one command, previewed, backed up, reversible.
+
+**Architecture:** A per-agent target module edits each agent's user-level MCP config (JSON for Claude Code/Cursor/Gemini, TOML via `tomlkit` for Codex) with read → merge → backup → write → verify, never touching unrelated entries. Skills ship inside the wheel and are copied to `~/.claude/skills` (Claude Code) and `~/.agents/skills` (Codex, Cursor, Gemini). REA is registered by delegating to REA's own non-interactive setup.
+
+**Tech Stack:** Python ≥3.10 stdlib (json, shutil, importlib.resources, subprocess), `tomlkit` (new dependency, comment-preserving TOML). Tests: pytest with a fake HOME.
+
+**Spec:** `docs/superpowers/specs/2026-10-20-mcp-everything-design.md` (G6; decisions 8, 9). Research facts (2026-10-21) are recorded in Global Constraints below.
+
+## Global Constraints
+
+- Config locations (user level): Claude Code `~/.claude.json` (`$CLAUDE_CONFIG_DIR/.claude.json` if set), key `mcpServers.<name>` = `{"type":"stdio","command","args","env"}`; Codex `~/.codex/config.toml` (`$CODEX_HOME` if set), table `[mcp_servers.<name>]` with `command`, `args`, `startup_timeout_sec = 30`, sub-table `env`; Cursor `~/.cursor/mcp.json`, `mcpServers.<name>` = `{"type":"stdio","command","args","env"}`; Gemini `~/.gemini/settings.json` (`$GEMINI_CLI_HOME/.gemini/settings.json` if set), `mcpServers.<name>` = `{"command","args","env","timeout":30000}`.
+- Skills: Claude Code `~/.claude/skills/<name>/`; Codex, Cursor, Gemini `~/.agents/skills/<name>/`. Skill folder name equals its frontmatter `name`.
+- Server entries (names exactly): `mcpsmith` → `uvx mcpsmith@<package version> mcp`; `chrome-devtools` → `npx -y chrome-devtools-mcp@1.11.0 --browser-url=http://127.0.0.1:9222`; REA → delegated: `npx -y rea-agents@6.7.0 setup --client <id> --yes` with ids `claude_code`, `codex`, `cursor`, `gemini_cli`.
+- On Windows, `npx` commands are written as `command: "cmd"`, `args: ["/d","/c","npx",...]`; `uvx` stays as is.
+- `env` written for the `mcpsmith` entry: `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` from setup's environment when set, with userinfo (`user:pass@`) stripped (reuse `browser.clean_proxy`); never write any other secret.
+- Never modify or remove entries mcpsmith did not create; preserve TOML comments and unrelated tables; JSON written with 2-space indent and UTF-8, original key order kept.
+- Before the first write to a file: copy it to `<file>.mcpsmith.bak` (do not overwrite an existing backup). After writing, re-read and verify the entry; on failure restore the backup and report.
+- Node.js missing (`npx` not on PATH) → skip `chrome-devtools` and REA with one clear line each; still do the rest.
+- Default asks for confirmation after printing the plan; `--yes` skips it; `--dry-run` prints the plan and writes nothing; non-interactive stdin without `--yes` → error, exit 2.
+- New dependency only: `tomlkit>=0.12`. Existing behaviour stays; full suite green; ruff clean; commits on branch `feat/setup` without AI attribution.
+
+## Review Focus
+
+1. Existing user configs with unrelated servers, comments (TOML) and other top-level keys → untouched after setup and after `--remove`. (Task 2 tests.)
+2. Running setup twice → idempotent: no duplicate entries, no second backup overwrite. (Task 3 test.)
+3. A config file that is malformed JSON/TOML → that agent is skipped with a clear message; nothing written to it. (Task 2 test.)
+4. Proxy env with credentials → credentials never written. (Task 2 test.)
+5. Agent not installed → not touched unless named with `--agents`. (Task 3 test.)
+
+---
+
+### Task 1: Ship skills in the package
+
+**Files:** Modify `pyproject.toml`; Create `src/mcpsmith/skills_path.py`; Test `tests/test_setup.py`
+
+**Interfaces:**
+- Produces: `skills_path.skills_dir() -> Path` — the packaged skills directory (`importlib.resources.files("mcpsmith") / "skills"` when present, else the repo's `skills/` for editable installs); contains `build-mcp-server`, `design-mcp-tools`, `extract-api`.
+
+- [ ] **Step 1:** Test `test_skills_dir_has_all_skills`: the three folders exist, each with a `SKILL.md` whose frontmatter `name` equals the folder name. Test `test_wheel_contains_skills`: `uv build --wheel` into `tmp_path`, the wheel's namelist contains `mcpsmith/skills/extract-api/SKILL.md` (mark the test `slow` only if it exceeds 20 s).
+- [ ] **Step 2:** Run → FAIL. **Step 3:** Add `[tool.hatch.build.targets.wheel.force-include] "skills" = "mcpsmith/skills"`; implement `skills_dir`. **Step 4:** Run full suite → PASS. **Step 5:** Commit `build: ship skills inside the package`.
+
+### Task 2: Agent targets
+
+**Files:** Create `src/mcpsmith/setup/__init__.py`, `src/mcpsmith/setup/agents.py`; Modify `pyproject.toml` (`tomlkit`); Test `tests/test_setup.py`
+
+**Interfaces:**
+- Produces:
+  - `SERVERS: dict[str, list[str]]` — base commands per server name (from Global Constraints), and `server_entry(name: str, windows: bool, env: dict[str,str]) -> dict` (command/args, Windows `cmd /d /c` wrapping for npx).
+  - `class Agent` (one per agent: `claude`, `codex`, `cursor`, `gemini`) with `id`, `rea_client`, `config_path(home: Path, environ) -> Path`, `skills_root(home) -> Path`, `detected(home, environ, which) -> bool` (config dir exists or CLI on PATH), `add(doc, name, entry) -> doc`, `remove(doc, name) -> doc`, `has(doc, name) -> bool`, `load(path) -> doc` (raises `ValueError` on malformed), `dump(doc) -> str`.
+  - `AGENTS: dict[str, Agent]`.
+- [ ] **Step 1:** Tests on in-memory docs: each agent adds `mcpsmith` and `chrome-devtools` with exact shapes from Global Constraints; unrelated servers/keys preserved; Codex TOML comment and an unrelated `[mcp_servers.other]` survive add+remove; `remove` deletes only our names; malformed JSON/TOML → `ValueError`; `server_entry("chrome-devtools", windows=True, …)` → `command == "cmd"`, args start `["/d","/c","npx","-y","chrome-devtools-mcp@1.11.0"]`; mcpsmith env from `HTTPS_PROXY=http://u:p@h:1` → `"http://h:1"`; `CLAUDE_CONFIG_DIR`/`CODEX_HOME`/`GEMINI_CLI_HOME` honored.
+- [ ] **Step 2:** Run → FAIL. **Step 3:** Implement. **Step 4:** Full suite → PASS. **Step 5:** Commit `feat(setup): agent config targets`.
+
+### Task 3: `mcpsmith setup` command
+
+**Files:** Create `src/mcpsmith/setup/run.py`; Modify `src/mcpsmith/cli.py`; Test `tests/test_setup.py`
+
+**Interfaces:**
+- Consumes: `AGENTS`, `server_entry`, `skills_dir`.
+- Produces: CLI `mcpsmith setup [--agents claude,codex,cursor,gemini] [--no-rea] [--no-skills] [--dry-run] [--yes] [--remove]`; `plan(home, environ, agents, rea, skills, remove) -> list[Change]` (`Change`: agent, kind `server|skill|rea`, target path or command, action `add|update|remove|skip`, reason); `apply(changes, runner=subprocess.run) -> list[str]` (result lines).
+- Behaviour: detected agents by default (or `--agents`); prints the plan (paths, entries, skill folders, REA command), asks `Apply these changes? [y/N]` unless `--yes`/`--dry-run`; per file backup→write→verify (restore on verify failure); skills copied with `shutil.copytree(dirs_exist_ok=True)` (only mcpsmith's three folders; `--remove` deletes only those); REA via `runner([npx..., "setup", "--client", id, "--yes"])` (Windows-wrapped), `--remove` → `rea-agents@6.7.0 uninstall --client id --yes`; final line tells the user to restart their agents and to run `mcpsmith browser` before using Chrome DevTools.
+- [ ] **Step 1:** Tests with fake HOME and stub `which`/runner: `--dry-run` writes nothing and lists every change; a real run writes entries + skills + backups and calls REA once per agent with the right client id; second run → no changes reported as `add`, backups unchanged; `--remove` restores a config equal to the original except formatting (JSON) / byte-identical comments (TOML), skills gone; undetected agent untouched; malformed config → that agent skipped, others done; no `npx` → chrome-devtools and REA skipped with messages; stdin not a TTY and no `--yes` → exit 2.
+- [ ] **Step 2:** Run → FAIL. **Step 3:** Implement. **Step 4:** Full suite → PASS. **Step 5:** Commit `feat: mcpsmith setup registers the bundle with coding agents`.
+
+### Task 4: Plugin, docs, release 0.3.0
+
+**Files:** Modify `.claude-plugin/plugin.json` (add `chrome-devtools` and `rea` servers, pinned, same args as setup on non-Windows), `README.md` (Install section: `uvx mcpsmith setup`; plugin users don't also run setup), `AGENTS.md`, `skills/build-mcp-server/SKILL.md` (setup line), version 0.3.0 in all version spots; `uv lock`.
+
+- [ ] **Step 1:** `claude plugin validate .` → "Validation passed"; `uv run pytest -q`; ruff.
+- [ ] **Step 2: Acceptance** — run `mcpsmith setup --dry-run` on the real machine and show the plan; run the real setup with `HOME`/`USERPROFILE` pointed at a scratch dir seeded with copies of the four real config files (no real config touched) and check: entries added, comments/unrelated servers preserved, `--remove` reverts. Real-machine install only with the user's yes.
+- [ ] **Step 3:** Commit `chore: release 0.3.0`; PR `feat/setup` → main; CI green; merge; tag `v0.3.0`; publish workflow green.

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcpsmith"
-version = "0.2.2"
+version = "0.4.0"
 description = "Turn an OpenAPI file or a recorded website session into a curated, tested MCP server, with an LLM designing the tools."
 readme = "README.md"
 license = "MIT"
@@ -27,6 +27,7 @@ dependencies = [
     "websockets>=12",
     "keyring>=25",
     "tzdata>=2024.1; sys_platform == 'win32'",
+    "tomlkit>=0.12",
 ]
 
 [project.optional-dependencies]
@@ -49,6 +50,9 @@ dev = ["pytest>=8", "anyio>=4", "ruff>=0.6"]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.build.targets.wheel.force-include]
+"skills" = "mcpsmith/skills"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-m 'not live'"

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/server.json

@@ -8,13 +8,13 @@
     "source": "github"
   },
   "websiteUrl": "https://github.com/sepehr071/mcpsmith",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "packages": [
     {
       "registryType": "pypi",
       "registryBaseUrl": "https://pypi.org",
       "identifier": "mcpsmith",
-      "version": "0.2.2",
+      "version": "0.4.0",
       "runtimeHint": "uvx",
       "transport": {
         "type": "stdio"

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/skills/build-mcp-server/SKILL.md

@@ -5,6 +5,8 @@ description: Build a curated, tested MCP server (agent tools) with mcpsmith. Use
 
 # Build an MCP server with mcpsmith
 
+Not set up yet? `uvx mcpsmith setup` registers mcpsmith, Chrome DevTools MCP and REA with the user's agents.
+
 mcpsmith turns an OpenAPI file or a recorded website session (HAR) into a Python MCP server project with tests, CI, a publish workflow and a Claude Code plugin. You design the tools; mcpsmith generates and checks the code.
 
 Run commands with `uvx mcpsmith <cmd>` (or `mcpsmith <cmd>` if installed). No shell? Use the mcpsmith MCP tools instead: `smith_guide`, `smith_inspect`, `smith_draft`, `smith_validate`, `smith_generate`, `smith_check`, and the hub tools `smith_record_start`, `smith_record_stop`, `smith_connect`, `smith_disconnect`, `smith_connections`, `smith_tools`, `smith_call` (paths absolute).

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/skills/extract-api/SKILL.md

@@ -65,6 +65,22 @@ Call each connected tool once with a real input. Open the same view in Chrome (`
 
 If a call says the session expired, ask the user to log in again in the shared Chrome window, then retry.
 
+## Desktop program (own or authorized)
+
+For a desktop program's API, the developer records the program's own traffic with their own proxy; mcpsmith imports the HAR. Use this only for software the user owns or is authorized to analyze; certificate-pinned programs are out of scope, and you offer no way around that.
+
+1. Call `smith_app_desktop(workdir=<dir>)` and show the user the steps. The user installs and runs mitmproxy (`mitmdump --set hardump=<file>`), points that one program at it (the program must trust mitmproxy's CA for HTTPS, per mitmproxy's certificate docs), uses the features they want as tools, and stops mitmdump with Ctrl-C (mitmweb: quit from the UI). Killing the process writes no HAR. Safer: record with `mitmdump -p <port> -w flows.mitm`, then convert with `mitmdump -nr flows.mitm --set hardump=<file>`. You never install, start or configure the proxy, install a certificate or change system proxy settings yourself.
+2. Call `smith_app_desktop(har=<file>, hosts=[<the program's API host>], workdir=<dir>)`. Other programs' traffic on the same proxy is dropped by `hosts`. If it says nothing to import, the capture holds no JSON API calls: ask the user to record again.
+3. Continue at step 4 (`smith_draft`). The endpoints came from real responses, so they are verified. Delete the HAR afterwards (step 6).
+
+## Android app (own or authorized)
+
+Only for an app the user owns or is authorized to analyze; nothing is run or bypassed. Call `smith_app_android(apk=<abs path>, base_url=<API base URL>, workdir=<dir>)` (needs REA's JADX jar; `REA_JADX_MCP_JAR`). Without `class_name` it lists candidate Retrofit classes: pick one and call again. Endpoints are read from code, so they are unverified until `smith_probe(workdir)` calls the GET ones with the user's credentials (`writes=true` only after the user confirms). A method or parameter kind that could not be read is listed in `source.json` `description`: an endpoint with no method fails `smith_validate` until you set it in the plan. Then continue at step 4.
+
+## Electron / JavaScript app (own or authorized)
+
+Same rules. Call `smith_app_js(path=<app dir, app.asar or one file>, base_url=<API base URL>, workdir=<dir>)`. Calls whose path is built at run time are skipped and noted, never guessed. Endpoints are unverified until `smith_probe(workdir)`; set `base_url` first or probe refuses. Then continue at step 4.
+
 ## 6. Privacy and publishing
 
 - Tool results go to the model like any conversation text. Tell the user which personal fields the tools return and trim `fields` they do not need.

{mcpsmith-0.2.2 → mcpsmith-0.4.0}/src/mcpsmith/__init__.py

@@ -1,3 +1,3 @@
 """mcpsmith: turn an OpenAPI file or a recorded website session into a curated, tested MCP server."""
 
-__version__ = "0.2.2"
+__version__ = "0.4.0"