@wootsup/mcp 0.1.0-rc.1

package/docs/customgraph-internal-migration.md

@@ -0,0 +1,210 @@
+# CustomGraph internal-use migration
+
+CustomGraph (Pipeline Studio, `~/Projekte/customgraph/`) is the
+**first internal consumer** of `@wootsup/mcp`. Today it ships a
+local-build adapter — `packages/mcp-adapter-apimapper/` — wired
+through a shell wrapper. Once Task 10.4 publishes `@wootsup/mcp` to
+npm (G2 gate), the wrapper goes away and CustomGraph consumes the
+published package like every external customer.
+
+This document is a **prep tracker only**. No file outside
+`packages/apimapper-mcp/` is modified by this commit.
+
+## Files involved
+
+| File | Repo | Role |
+|---|---|---|
+| `~/.claude.json` | (user home) | Claude Code MCP-server registry. The `apimapper` entry lives here. |
+| `~/.claude-tools/run-mcp-apimapper.sh` | (user home) | Today's wrapper. Sets env + execs the local-build adapter. |
+| `packages/mcp-adapter-apimapper/` | `customgraph` repo | Local-build adapter that the wrapper currently invokes. |
+
+## BEFORE state (today, 2026-05-18)
+
+### `~/.claude.json` (relevant slice)
+
+```json
+"apimapper": {
+  "type": "stdio",
+  "command": "/Users/getimo/.claude-tools/run-mcp-apimapper.sh",
+  "args": []
+}
+```
+
+### `~/.claude-tools/run-mcp-apimapper.sh`
+
+```bash
+#!/bin/bash
+# Wrapper for apimapper MCP adapter — hardcodes env vars.
+export DEVTOOLS_URL="https://dev.wootsup.com/dev-tools/api"
+export WP_BASE_URL="https://dev.wootsup.com/wordpress"
+export JOOMLA_BASE_URL="https://dev.wootsup.com/joomla"
+export NODE_ENV="production"
+cd /Users/getimo/Projekte/customgraph
+exec bun packages/mcp-adapter-apimapper/dist/index.js
+```
+
+**Drawbacks of this setup:**
+
+- Depends on a built local checkout of `customgraph` at a hard-coded
+  path. If that checkout is moved or the `dist/` is stale, the MCP
+  server breaks.
+- Uses `bun` (CustomGraph's runtime) instead of Node — divergence from
+  the public package's tested runtime.
+- Env vars (`WP_BASE_URL`, `JOOMLA_BASE_URL`) are the legacy contract;
+  the published package uses `APIMAPPER_SITE_URL` + `APIMAPPER_PLATFORM`
+  with a runtime bridge in `src/index.ts`.
+- No keychain integration — credentials live in the wrapper as env
+  vars, not encrypted at rest.
+
+## AFTER state (post-G2)
+
+### `~/.claude.json` (relevant slice)
+
+```json
+"apimapper": {
+  "type": "stdio",
+  "command": "npx",
+  "args": ["-y", "@wootsup/mcp@latest"],
+  "env": {
+    "APIMAPPER_PROFILE": "default"
+  }
+}
+```
+
+That's it. The token + site URL come from the OS keychain (or
+`~/.config/apimapper-mcp/profiles/default.json` fallback), set during
+`npx @wootsup/mcp setup`.
+
+### Wrapper script
+
+Deprecated. Either delete `~/.claude-tools/run-mcp-apimapper.sh` or
+keep it around as a backup pointing at the local dev build for
+adapter-internal debugging. Recommend: rename to `.bak` for one cycle,
+then delete.
+
+## Migration steps (post-G2 only — do not execute now)
+
+1. **Confirm npm publish succeeded**
+
+   ```bash
+   gh run list \
+     --workflow apimapper-mcp-publish.yml \
+     --limit 1 --json conclusion,name,status,databaseId
+   ```
+
+   Expect `conclusion: success`, both `publish-npm` and `publish-dxt`
+   jobs green.
+
+2. **Confirm npm registry has the version**
+
+   ```bash
+   npm view @wootsup/mcp version
+   # Expect: 0.1.0-rc.1 (or whatever the published tag was)
+
+   npm view @wootsup/mcp dist-tags
+   # Expect: { latest: ..., rc: '0.1.0-rc.1' } for the rc tag
+   ```
+
+3. **Run the setup wizard with the published package**
+
+   ```bash
+   npx -y @wootsup/mcp@latest setup
+   ```
+
+   This:
+   - Auto-detects Claude Code (`~/.claude.json`).
+   - Prompts for site URL + MCP key.
+   - Runs identity-probe handshake.
+   - Writes the new `apimapper` entry (idempotent — replaces the
+     existing one).
+   - Stores the token in the macOS keychain under the `default`
+     profile.
+
+4. **Manual sanity check on `~/.claude.json`**
+
+   Confirm the entry now matches the AFTER state above. Note: the
+   wizard writes `command: "npx"` and `args: ["-y", "@wootsup/mcp@latest"]`
+   exactly — if it picks a different shape, file an issue against
+   the wizard (`src/setup-cli.ts`).
+
+5. **Move the wrapper out of the way**
+
+   ```bash
+   mv ~/.claude-tools/run-mcp-apimapper.sh \
+      ~/.claude-tools/run-mcp-apimapper.sh.bak
+   ```
+
+6. **Restart Claude Code**
+
+   The MCP server is launched at session start. A `/mcp` slash-command
+   shows the loaded servers — `apimapper` should report **connected**
+   with the new `npx` command line.
+
+7. **Verify `apimapper_health` works**
+
+   In a Claude Code session:
+
+   ```
+   apimapper_health
+   ```
+
+   Expect:
+
+   ```
+   status: ok
+   platform: wordpress (or joomla)
+   site_url: https://dev.wootsup.com/wordpress
+   plugin_version: 2.0.7
+   tool_count: 74
+   ```
+
+8. **Run the full smoke suite**
+
+   ```
+   apimapper_onboarding
+   apimapper_connection_list
+   apimapper_flow_list
+   ```
+
+   All three should return tables. If any returns
+   `403 invalid_token`, re-run step 3.
+
+## Rollback
+
+If any step fails:
+
+```bash
+# Restore the wrapper
+mv ~/.claude-tools/run-mcp-apimapper.sh.bak \
+   ~/.claude-tools/run-mcp-apimapper.sh
+
+# Revert ~/.claude.json (manual edit; jq if you have it)
+# — set the `apimapper` entry back to the BEFORE shape above.
+```
+
+Restart Claude Code. The local-build adapter is back in play.
+
+## Open question: when to drop the CustomGraph adapter?
+
+`packages/mcp-adapter-apimapper/` in the CustomGraph repo becomes
+obsolete after the migration — its 65-tool surface is now in
+`@wootsup/mcp`, and the wrapper is gone. **Removal is a separate
+session**: it requires Auditing CustomGraph for any other consumer
+(none expected — the only caller was Claude Code via the wrapper)
+and a deprecation note in the CustomGraph CHANGELOG.
+
+Filed as a CustomGraph followup, not part of API Mapper Phase 10.
+
+## Out-of-scope reminder
+
+This document is **prep only**. The actual migration is gated on:
+
+- ✅ Task 10.1 (CI) — done.
+- ✅ Task 10.2 (publish workflow) — done.
+- ✅ Task 10.3 (docs) — done.
+- ⏳ **Task 10.4 (G2 user-gate) — pending Thomas's approval.**
+- ⏳ Task 10.5 (this migration) — executes after 10.4.
+- ⏳ Task 10.6 (stable v1.0.0) — separate cycle.
+
+Until Task 10.4 lands, do not modify `~/.claude.json` or
+`~/.claude-tools/`.

package/docs/security.md

@@ -0,0 +1,126 @@
+# Security Model
+
+Long-form threat model and mitigations for `@wootsup/mcp`. For the
+reporting process and supported-version policy, see
+[`../SECURITY.md`](../SECURITY.md).
+
+## Threat model
+
+| ID | Threat | Likelihood | Impact | Mitigation |
+|----|--------|------------|--------|------------|
+| T1 | Token leak via logs / stderr | Med | High | All response sanitizer (`credential-sanitizer.ts`); no token in stack traces; pin tests assert. |
+| T2 | Token leak via tool response | Low | Critical | List endpoints structurally omit token string; tests pin redaction surface. |
+| T3 | Token replay across sites | Med | High | HMAC includes site URL; cross-site replay fails server-side signature check. |
+| T4 | Forged tokens | Low | Critical | Signing key never leaves the install; tokens unforgeable without it. |
+| T5 | Phishing setup link | Med | Med | Identity probe + site-title confirmation in wizard; user must explicitly confirm. |
+| T6 | Confused-deputy LLM (read-only token gets `*_delete` tools listed) | High | Med | Scope filter excludes destructive tools from tool-list when the token lacks the scope. |
+| T7 | Local-fs token theft (no keychain) | Med | Med | `0600` file mode; keychain default on macOS/Windows; SECURITY.md warns about multi-user environments. |
+| T8 | DXT supply-chain (malicious .dxt) | Low | Critical | DXT bundle uploaded as a signed GitHub Release asset; `apimapper-mcp-publish.yml` workflow publishes with `--provenance`. |
+| T9 | OAuth callback hijack (HTTP transport) | Med | High | PKCE-required (S256); state param checked; loopback callback only. |
+| T10 | TOCTOU on rotate (old token works after rotate UI shows success) | Low | Med | Rotation is atomic on the server; the response shows the new token only after the old one is invalidated. |
+
+## Token rotation
+
+- **From admin UI:** API Mapper → Connections → MCP Access → **Rotate**.
+- **From CLI:** `apimapper_credential_*` tools do **not** rotate MCP keys
+  themselves — by design, key rotation is an admin-UI gesture (not a
+  tool the LLM can call) to prevent confused-deputy rotation. Rotation
+  is intentionally human-in-the-loop.
+- After rotation, the next request with the old token returns
+  `403 invalid_token`. The user re-runs `npx @wootsup/mcp setup` to
+  paste the new key.
+
+## Revocation
+
+- Per-token revoke is immediate (no server-side cache).
+- "Revoke all" also rotates the signing key — invalidates every active
+  token in one operation. Use after suspected compromise.
+
+## Scope semantics
+
+| Scope | Tools | Default for amk_test_? |
+|---|---|---|
+| `read` | `*_list`, `*_get`, `*_inspect`, `apimapper_health`, `apimapper_onboarding` | ✅ |
+| `write` | `*_create`, `*_update`, `*_compile`, `*_publish` | ✅ |
+| `destructive` | `*_delete`, `apimapper_settings_reset_demo`, `apimapper_license_deactivate` | ❌ |
+| `oauth` | `apimapper_credential_create`, `apimapper_oauth_authorize_begin` | ✅ |
+
+The MCP server **filters tool registration by available scopes**. A
+token without `destructive` scope causes the matching tools to be
+omitted from `tools/list` entirely — the LLM cannot accidentally
+suggest them.
+
+## Anti-phishing identity probe
+
+When the wizard contacts an unverified site URL:
+
+1. `GET <url>/api-mapper/v1/mcp/identity` (no auth).
+2. Server responds with `{ key_id, site_title, site_signature }`
+   where `site_signature = HMAC(signing_key, key_id + site_url + nonce)`.
+3. Wizard decodes the token to extract its `key_id` claim.
+4. Wizard sends a second probe with the token; server proves it can
+   sign over the same nonce.
+5. User sees: **"You are connecting to: '<site_title>' (<site_url>).
+   Proceed?"** with explicit confirm.
+
+A malicious server cannot pass both probes because it lacks the genuine
+signing key. The user-visible site title (rendered by the wizard from
+the server's response, not the URL bar) gives one more verification
+surface for the user.
+
+## OAuth 2.0 PKCE (HTTP transport)
+
+When `@wootsup/mcp` runs in HTTP mode:
+
+- **Grants supported:** `authorization_code` with PKCE-S256 only.
+- **Implicit grant:** disabled.
+- **`code` grant without PKCE:** rejected with `invalid_request`.
+- **Loopback callbacks only:** `redirect_uri` must be
+  `http://127.0.0.1:<port>/callback` or `http://localhost:<port>/callback`.
+- **State param:** required and verified.
+- **Origin header:** Bearer tokens are bound to the issuing site URL.
+  A request from a different `Origin` is rejected (`401`).
+- **Token TTL:** 1 hour. Refresh tokens are not issued — the client
+  re-runs the auth flow.
+
+See `src/server-http.ts` for the implementation and
+`src/server-http.test.ts` (2 tests) + `src/transports/http.test.ts`
+(10 tests) for the pinning.
+
+## Keychain fallback security
+
+When `@napi-rs/keyring` cannot reach an OS keychain:
+
+1. The wizard prints a warning: **"OS keychain unavailable. Falling
+   back to ~/.config/apimapper-mcp/profiles/<name>.json (mode 0600)."**
+2. The user explicitly confirms before any token is written to disk.
+3. The file is written with mode `0600` (owner-only) on POSIX. On
+   Windows, NTFS ACL is set to the current user only.
+4. The file contains the bare token string + the site URL — no
+   signing key, no signature data.
+
+**Hostile-multi-user environments:** Even with `0600`, a root user can
+read the file. If you operate in such an environment, use the OS
+keychain path explicitly (it is the default on macOS/Windows; on Linux
+install `libsecret` to enable it).
+
+## Sanitization surface
+
+The `CredentialSanitizer` runs in two places:
+
+1. **Server-side**, in the WordPress / Joomla plugin — every REST
+   response is rewritten to mask credential values (`***`) before
+   transit.
+2. **Client-side**, in `@wootsup/mcp` — defense-in-depth. If a
+   server forgets to sanitize (or a new endpoint is added without the
+   wrap), the MCP server still won't leak the value to the LLM.
+
+Unit tests pin both sides:
+
+- `src/modules/apimapper/credential-sanitizer.test.ts` (client side).
+- `tests/Unit/Auth/CredentialSanitizerTest.php` (server side, in the
+  main plugin repo).
+
+## Reporting
+
+See [`../SECURITY.md`](../SECURITY.md).

package/docs/tools.md

@@ -0,0 +1,230 @@
+# Tools reference
+
+Auto-extracted from `src/modules/apimapper/*.ts` on **2026-05-18**.
+
+To regenerate after adding tools, run:
+
+```bash
+cd packages/apimapper-mcp
+node scripts/extract-tools.mjs
+```
+
+…and paste the `---MD---` output into the sections below. (The
+extractor is intentionally simple; a fully auto-generated build-step
+is tracked as a future improvement.)
+
+## Summary
+
+- **Total tools:** 74 registered (+ a few system surfaces brought in
+  via `@getimo/mcp-toolkit`).
+- **Annotation breakdown:** 43 `readOnly`, 15 `mutating`, 10 `creating`,
+  6 `destructive`.
+
+The annotation tells the AI client what kind of side-effect each tool
+has. Destructive tools additionally require a `confirm: true`
+parameter — see the
+[Goldstandard skill](../../../docs/MCP-Module-Goldstandard.md) (private
+vault) for the full convention.
+
+## Quick map
+
+| Module | Tools | Notes |
+|---|---:|---|
+| `connections.ts` | 11 | CRUD + probe + sample-data + resources |
+| `flows.ts` | 11 | CRUD + compile + import/export + trace |
+| `library.ts` | 9 | Catalog + activate / deactivate templates |
+| `credentials.ts` | 7 | CRUD + link + OAuth begin |
+| `settings.ts` | 7 | Settings + features + platform parity + warnings |
+| `license.ts` | 6 | Activate / status / beta-channel / refresh |
+| `local-sources.ts` | 4 | WP posts/users, Joomla articles, …  |
+| `misc.ts` | 4 | Releases + Brandfetch + feedback |
+| `workflows.ts` | 3 | Composite multi-step ops |
+| `graph.ts` | 2 | Preview + validate |
+| `cache.ts` | 2 | Stats + invalidate |
+| `schema.ts` | 2 | Profile + snapshot list |
+| `onboarding.ts` | 1 | Composite startup report |
+| `diagnose.ts` | 1 | Composite token + identity probe |
+| `inspect.ts` | 1 | Token decode (network-free) |
+| `get-skill.ts` | 1 | Read bundled skill doc |
+| `use-profile.ts` | 1 | Switch active profile |
+| `index.ts` | 1 | `apimapper_rest_modules_status` |
+
+### Adapter Status (`index.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_rest_modules_status` | `readOnly` | Module-loading status for this MCP adapter (which sub-modules registered cleanly). |
+
+### Health, Releases, Brandfetch & Feedback (`misc.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_brandfetch` | `readOnly` | Fetch a brand's logo metadata via the Brandfetch proxy. |
+| `apimapper_feedback_submit` | `creating` | Submit user feedback (bug report, feature request, support question) to the API Mapper team. |
+| `apimapper_release_download` | `creating` | Request a signed download URL for a release ZIP. |
+| `apimapper_release_list` | `readOnly` | List API Mapper plugin releases available for download. |
+
+### Onboarding (`onboarding.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_onboarding` | `readOnly` | Aggregate health, license, connections, flows, and popular library items into a single onboarding report with suggested next actions. |
+
+### Diagnose (`diagnose.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_diagnose` | `readOnly` | Validate a token + siteUrl pair before profile creation (token decode + identity probe + reachability). |
+
+### Token Inspection (`inspect.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_inspect_token` | `readOnly` | Decode an API Mapper token (`amk_live_…` or `amk_test_…`) WITHOUT calling the network. |
+
+### Connections (`connections.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_connection_create` | `creating` | Create a new connection (custom — not from library). |
+| `apimapper_connection_data` | `readOnly` | Fetch sample data from a connection's configured endpoint. |
+| `apimapper_connection_delete` | `destructive` | Permanently delete a connection. Any flow referencing it will break. |
+| `apimapper_connection_get` | `readOnly` | Fetch full configuration of a single connection by ID. |
+| `apimapper_connection_health_check` | `readOnly` | Probe a set of connections in one batch and report status. May take 10-30s. |
+| `apimapper_connection_list` | `readOnly` | List all API Mapper connections. Use `apimapper_connection_get` for full details. |
+| `apimapper_connection_pipeline_update` | `mutating` | Update the connection's pipeline (endpoints, default_params, headers, items_path, items_shape). |
+| `apimapper_connection_resources` | `readOnly` | List browseable resources on a connection (drive files, sheets, IG media). |
+| `apimapper_connection_test` | `readOnly` | Probe a connection's upstream endpoint to verify reachability + auth. |
+| `apimapper_connection_update` | `mutating` | Update fields on an existing connection. Only provided fields are changed; wire-format is snake_case. |
+| `apimapper_health` | `readOnly` | Check connectivity + auth against the API Mapper REST namespace. |
+
+### Credentials & OAuth (`credentials.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_credential_create` | `creating` | Create a new credential. Secrets are encrypted server-side. REST contract uses snake_case keys: `auth_type`, `auth_data`, `oauth_provider`. |
+| `apimapper_credential_delete` | `destructive` | Permanently delete a credential. Any connection using it will lose auth. |
+| `apimapper_credential_get` | `readOnly` | Fetch credential metadata. **Secret values are stripped at the MCP boundary** (`auth_data`, `refresh_token`, `access_token`, `api_key` → `'[REDACTED]'`). |
+| `apimapper_credential_link` | `mutating` | Attach a credential to a connection. PUT `/connections/{id}` with `credential_id`. |
+| `apimapper_credential_list` | `readOnly` | List all stored credentials (sanitised — secrets omitted). |
+| `apimapper_credential_update` | `mutating` | Update credential metadata or rotate secret. |
+| `apimapper_oauth_authorize_begin` | `creating` | Initiate the OAuth2 authorization-code flow for a credential. Returns the upstream authorize URL the user opens in a browser. |
+
+### Flows (`flows.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_flow_compile` | `mutating` | Compile flow into executable pipeline (validation + topo sort + step generation + schema). |
+| `apimapper_flow_create` | `creating` | Create a new flow with full nodes + edges JSON. |
+| `apimapper_flow_delete` | `destructive` | Permanently delete a flow. If published, it disappears from YOOtheme. Preview-mode (`confirm:false`) fetches metadata first. |
+| `apimapper_flow_detect_schema` | `mutating` | Re-detect/refresh the output schema by sampling the upstream API. |
+| `apimapper_flow_export` | `readOnly` | Export a flow as a portable JSON bundle (incl. connection refs). |
+| `apimapper_flow_get` | `readOnly` | Fetch full flow definition (nodes, edges, viewport, compiled artifact). |
+| `apimapper_flow_import` | `creating` | Import a flow JSON bundle. Always validate first with `apimapper_flow_import_validate`. Rename via `bundle.data.flow.name` or `rename_to`. |
+| `apimapper_flow_import_validate` | `readOnly` | Validate a flow JSON bundle before importing. Reports missing connections, schema mismatches, conflicts. |
+| `apimapper_flow_list` | `readOnly` | List all API Mapper flows. Use `apimapper_flow_get` for full structure. |
+| `apimapper_flow_trace` | `readOnly` | Fetch the execution trace from the last run (timing per step, item counts, errors). |
+| `apimapper_flow_update` | `mutating` | Update flow fields. Use to modify nodes/edges (e.g., toggle merge.strategy, change joinKey). After update, call `apimapper_flow_compile`. |
+
+### Graph Preview / Validate (`graph.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_graph_preview` | `readOnly` | Execute an ad-hoc graph (nodes + edges) and return rendered items at the target node. |
+| `apimapper_graph_validate` | `readOnly` | Validate a graph's structure (cycles, disconnected nodes, missing outputs, type mismatches) WITHOUT executing the pipeline. |
+
+### Local Sources (`local-sources.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_local_source_filter_options` | `readOnly` | Fetch dropdown options for a filter on a local source (e.g., available categories/tags). |
+| `apimapper_local_source_query` | `readOnly` | Execute a query against a local source and return data. Body uses camelCase keys. |
+| `apimapper_local_source_schema` | `readOnly` | Fetch field schema for a local-source type (e.g., `wordpress/posts`). |
+| `apimapper_local_source_types` | `readOnly` | List available local-source types (e.g., `wordpress/posts`, `wordpress/users`, `joomla/articles`). |
+
+### Schema (`schema.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_node_snapshot_list` | `readOnly` | List node-level data snapshots (per-flow/per-node cached payloads used by preview hydrate path). |
+| `apimapper_schema_profile` | `readOnly` | Analyse a JSON payload and detect field names, types, nullability, sample values, and candidate `items_path`. |
+
+### Library (Templates) (`library.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_library_activate` | `creating` | Activate a library template — creates a new connection. |
+| `apimapper_library_activated` | `readOnly` | List library items the user has activated (= has a connection for). |
+| `apimapper_library_catalog` | `readOnly` | Fetch the entire library catalog (all categories + items + featured/popular in one shot). |
+| `apimapper_library_categories` | `readOnly` | Fetch all library category slugs + counts. |
+| `apimapper_library_connection_detail` | `readOnly` | Fetch the full connection template (endpoints, default_params, auth scheme) for one library item. |
+| `apimapper_library_deactivate` | `destructive` | Deactivate a library template — deletes the underlying connection. |
+| `apimapper_library_featured` | `readOnly` | Fetch curated/featured library items shown on the catalog landing. |
+| `apimapper_library_list` | `readOnly` | List all library items (connection templates) shipping with API Mapper. |
+| `apimapper_library_popular` | `readOnly` | Fetch most-activated library items. |
+
+### Cache (`cache.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_cache_invalidate` | `mutating` | Trigger admin-cache invalidation via the event bus. Pushes events to all subscribers (Admin-UI BroadcastChannel + render cache). |
+| `apimapper_cache_stats` | `readOnly` | Fetch cache observability stats (hits, misses, ttl distribution, sizes). |
+
+### Settings & Platform (`settings.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_features_get` | `readOnly` | Fetch the feature-flag matrix for the current license tier (Free/Pro/Developer). |
+| `apimapper_health_warnings_dismiss` | `mutating` | Dismiss a specific health-warning banner by ID. |
+| `apimapper_health_warnings_list` | `readOnly` | List active admin health-warnings (banners shown in the Admin UI). |
+| `apimapper_platform_parity` | `readOnly` | Compare feature parity between WordPress and Joomla versions of API Mapper. |
+| `apimapper_settings_get` | `readOnly` | Fetch all API Mapper plugin settings (telemetry, beta_channel, debug flags, etc.). |
+| `apimapper_settings_reset_demo` | `destructive` | Reset demo connections + demo flows back to factory state. Removes user modifications. |
+| `apimapper_settings_update` | `mutating` | Update plugin settings. Only provided keys are changed. Common keys: `beta_channel`, `debug_mode`, `telemetry_enabled`. |
+
+### License (`license.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_license_activate` | `creating` | Activate the API Mapper plugin with a license key. |
+| `apimapper_license_beta_channel` | `mutating` | Enable/disable the beta release channel for this license. |
+| `apimapper_license_deactivate` | `destructive` | Deactivate the license, freeing the activation slot. Plugin reverts to Free tier. |
+| `apimapper_license_refresh` | `mutating` | Refresh the local cache of the license response (no upstream call — faster than revalidate). |
+| `apimapper_license_revalidate` | `mutating` | Force a fresh validation call to the license server (network round-trip). |
+| `apimapper_license_status` | `readOnly` | Fetch the current license tier, expiry, beta-channel state, and feature flags. |
+
+### Composite Workflows (`workflows.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_flow_change_merge_strategy` | `mutating` | Toggle a flow's merge-node strategy (`append` ↔ `coalesce`) and re-compile. |
+| `apimapper_flow_full_recompile_publish` | `mutating` | Compile a flow + invalidate admin cache in one call. Use after upstream API changes. |
+| `apimapper_flow_setup_with_sources` | `creating` | Compose a complete flow from connections in one call. Sequence: create + add sources + compile + (optional) publish. |
+
+### Skill Doc (`get-skill.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_get_skill` | `readOnly` | Returns the markdown content of a bundled API Mapper skill doc. |
+
+### Profiles (`use-profile.ts`)
+
+| Tool | Annotation | Description |
+|------|------------|-------------|
+| `apimapper_use_profile` | `readOnly` | Activate a configured site profile and probe its identity endpoint to confirm the site is reachable and the plugin signature matches. |
+
+## Convention reminders
+
+- `readOnly` — no side effects; safe to retry.
+- `mutating` — modifies server state (idempotent).
+- `creating` — creates new server state (POST).
+- `destructive` — irreversible. **Always paired with a `confirm: true`
+  parameter and a preview guard**, per the Goldstandard.
+
+## Future work
+
+- Auto-generate this file in CI via `scripts/extract-tools.mjs` and
+  diff against the committed copy as a quality gate.
+- Add per-tool input-schema dumps (currently only name + annotation
+  are extracted).
+- Cross-link each tool to its source file with permalink anchors.

package/manifest.json

@@ -0,0 +1,76 @@
+{
+  "dxt_version": "0.1",
+  "name": "@wootsup/mcp",
+  "display_name": "API Mapper for WordPress & Joomla",
+  "version": "0.1.0-rc.1",
+  "description": "Build API integrations, OAuth credentials, and YOOtheme sources via natural conversation. Connects your AI assistant to API Mapper running on WordPress or Joomla.",
+  "author": {
+    "name": "WootsUp",
+    "url": "https://wootsup.com"
+  },
+  "homepage": "https://wootsup.com/products/api-mapper",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wootsup/api-mapper"
+  },
+  "license": "MIT",
+  "keywords": [
+    "api-mapper",
+    "wordpress",
+    "joomla",
+    "yootheme",
+    "mcp",
+    "claude"
+  ],
+  "server": {
+    "type": "node",
+    "entry_point": "dist/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/dist/index.js"
+      ],
+      "env": {
+        "APIMAPPER_TOKEN": "${user_config.APIMAPPER_TOKEN}",
+        "APIMAPPER_SITE_URL": "${user_config.APIMAPPER_SITE_URL}",
+        "APIMAPPER_PLATFORM": "${user_config.APIMAPPER_PLATFORM}"
+      }
+    }
+  },
+  "user_config": [
+    {
+      "key": "APIMAPPER_TOKEN",
+      "type": "string",
+      "title": "API Mapper MCP key",
+      "description": "Your amk_live_... key from API Mapper → Settings → MCP Keys",
+      "required": true,
+      "secret": true
+    },
+    {
+      "key": "APIMAPPER_SITE_URL",
+      "type": "string",
+      "title": "Site URL",
+      "description": "The base URL of your WordPress or Joomla site (e.g. https://example.com)",
+      "required": true
+    },
+    {
+      "key": "APIMAPPER_PLATFORM",
+      "type": "string",
+      "title": "Platform",
+      "description": "Either 'wordpress' or 'joomla'",
+      "required": true,
+      "default": "wordpress"
+    }
+  ],
+  "compatibility": {
+    "claude_desktop": ">=0.10.0",
+    "platforms": [
+      "darwin",
+      "win32",
+      "linux"
+    ],
+    "runtimes": {
+      "node": ">=22.0.0"
+    }
+  }
+}