@wootsup/mcp 0.1.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to `@wootsup/mcp` will be documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+this project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0-rc.1] - 2026-05-18 (unreleased)
+
+First public release candidate. Ships the full 74-tool MCP surface
+plus a complete setup story (`npx setup` wizard + Claude Desktop DXT
+bundle). Built across Phases 0–10 of the
+`apimapper-mcp-implementation-plan` (vault).
+
+### Added
+
+- **Stripe-style HMAC-SHA256 auth.** `amk_live_…` / `amk_test_…`
+  token format, server-side signing key, identity-probe handshake
+  with site-title confirmation in the setup wizard.
+- **WordPress plugin foundation.** REST routes under
+  `/wp-json/api-mapper/v1/mcp/*`, key generation UI under
+  *API Mapper → Connections → MCP Access*, key list + rotate +
+  revoke endpoints.
+- **Joomla plugin foundation.** Mirror surface via `com_ajax`
+  envelope; same key lifecycle as WordPress. Joomla envelope unwrap
+  is handled by the client layer transparently.
+- **5 admin UI components** for MCP key management: KeyList,
+  CreateKey, KeyDetail, RotateKey, RevokeKey — shared between
+  WordPress and Joomla via the platform abstraction.
+- **Platform abstraction.** Each MCP tool routes through a single
+  platform-router that detects WordPress vs. Joomla from the site
+  URL + `APIMAPPER_PLATFORM` env, then dispatches to the correct
+  REST shape.
+- **Keychain + Profiles.** OS keychain integration via
+  `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager,
+  Linux libsecret) with named profile support (`APIMAPPER_PROFILE`)
+  and a `0600` file fallback when no keychain is available.
+- **Setup CLI (`apimapper-mcp` binary).** Interactive
+  `@clack/prompts` wizard with subcommands: `setup` (default),
+  `install-skill`, `help`. Auto-detects Claude Desktop, Claude Code,
+  Cursor, VS Code, Cline, Codex. Idempotent config writers; rollback
+  on probe failure.
+- **Skills bundling.** `skills/apimapper/SKILL.md` plus four reference
+  docs (`oauth.md`, `joomla.md`, `yootheme.md`, `troubleshooting.md`)
+  shipped with every install. Resources surfaced via
+  `apimapper_get_skill` tool.
+- **Composite tools.** `apimapper_flow_setup_with_sources` (create
+  flow + add sources + compile + publish), `apimapper_diagnose`
+  (pre-flight: health + license + platform parity + connection probe
+  + recent flow status). Reduces multi-turn back-and-forth for the
+  most common workflows.
+- **Multi-transport.** stdio transport (default, local install) plus
+  HTTP transport with OAuth 2.0 (PKCE-required, S256) for remote
+  consumption. Bearer tokens are site-bound (rejected on origin
+  mismatch).
+- **DXT bundle.** `apimapper-mcp.dxt` packaged via `build-dxt.js`
+  for one-click Claude Desktop install. User-config keys
+  (`APIMAPPER_TOKEN`, `APIMAPPER_SITE_URL`, `APIMAPPER_PLATFORM`)
+  bridged into the runtime via env shimming. Build verified with a
+  grep-gate that ensures every declared user-config key has a
+  runtime consumer.
+- **74 MCP tools** spanning: connections, credentials, flows, graph
+  preview/validate, local sources, schema profile, library catalog,
+  cache, settings, license, releases, brandfetch, feedback,
+  workflows, plus health / onboarding / diagnose / inspect-token /
+  use-profile.
+
+### Engineering
+
+- **Test suite.** 243 tests across 27 files
+  (vitest + `tsx watch` dev). Includes a stdio-transport spawn
+  smoke-test, HTTP+Bearer transport tests, build-dxt manifest
+  invariants, and unit coverage of every register file.
+- **CI matrix.** ubuntu-latest, macos-latest, windows-latest × Node
+  22.x, gated by path filter and concurrency-cancel per ref
+  (`.github/workflows/apimapper-mcp-ci.yml`).
+- **Publish workflow.** Tag-triggered (`apimapper-mcp-v*`),
+  verifies tag-version vs. `package.json#version` before publishing,
+  publishes with `--provenance`, uploads DXT bundle to GitHub
+  Release (`.github/workflows/apimapper-mcp-publish.yml`).
+
+### Known issues
+
+- `@getimo/mcp-toolkit@1.0.0` declares a `workspace:*` peer-dep on
+  `@pipeline-studio/screenshot-capture` that is unresolvable outside
+  the source monorepo. Install with `npm install --legacy-peer-deps`
+  (or `npm ci --legacy-peer-deps` in CI). Tracked upstream; will be
+  fixed in `@getimo/mcp-toolkit@1.1.0`. Does not affect runtime —
+  `npx @wootsup/mcp` and the DXT bundle work without intervention.
+
+[0.1.0-rc.1]: https://github.com/wootsup/api-mapper/releases/tag/apimapper-mcp-v0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WootsUp / getimo productions
+
+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.

package/README.md

@@ -0,0 +1,179 @@
+# @wootsup/mcp
+
+**Build YOOtheme dynamic content via natural conversation.** The official MCP
+server for [API Mapper](https://wootsup.com/products/api-mapper) — connect
+your AI assistant to API Mapper running on WordPress or Joomla, then create
+flows, manage OAuth credentials, and publish sources without leaving the
+chat.
+
+[![npm version](https://img.shields.io/npm/v/@wootsup/mcp.svg)](https://www.npmjs.com/package/@wootsup/mcp)
+[![CI](https://github.com/wootsup/api-mapper/actions/workflows/apimapper-mcp-ci.yml/badge.svg)](https://github.com/wootsup/api-mapper/actions/workflows/apimapper-mcp-ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+---
+
+## Install
+
+Two paths, pick one.
+
+### Option A — `npx` (Claude Code, Cursor, VS Code, Cline, Codex, ChatGPT)
+
+```bash
+npx -y @wootsup/mcp setup
+```
+
+The interactive wizard:
+
+1. Asks which AI client(s) you use (auto-detected when possible).
+2. Prompts for your API Mapper site URL and MCP key.
+3. Runs an identity-probe handshake against your site.
+4. Patches the client's MCP config (`~/.claude.json`, `~/.cursor/mcp.json`,
+   VS Code `settings.json`, etc.) idempotently.
+5. Installs the bundled skill to `~/.claude/skills/apimapper/`.
+
+Re-run any time — writers are idempotent. Use `--help` to see all
+subcommands.
+
+### Option B — Claude Desktop (DXT bundle)
+
+1. Download `apimapper-mcp.dxt` from the latest
+   [GitHub Release](https://github.com/wootsup/api-mapper/releases?q=apimapper-mcp).
+2. Drag it onto the Claude Desktop window (or **Settings → Developer →
+   Install from file**).
+3. Enter your site URL, MCP key, and platform when prompted.
+
+## Setup (3 steps)
+
+1. **Install the API Mapper plugin** on your site:
+   - **WordPress:** plugin from
+     [wootsup.com](https://wootsup.com/products/api-mapper)
+   - **Joomla:** extension from
+     [wootsup.com](https://wootsup.com/products/api-mapper)
+2. **Generate an MCP key** in the admin:
+   - WordPress: click **API Mapper** in the WP admin menu — the flow
+     editor opens. In the editor header (top-right), click the **⋮**
+     (three-dot) menu → **Settings**. In the modal's left sidebar,
+     click **MCP Access** → **New API key**.
+   - Joomla: **Components → API Mapper** loads the same editor — use
+     the same **⋮** → **Settings** → **MCP Access** path.
+   - Token shape: `amk_live_…` (production) or `amk_test_…` (sandbox).
+3. **Run `npx -y @wootsup/mcp setup`** (or install the DXT) and paste
+   the key. The wizard verifies it with an HMAC-SHA256 identity probe
+   before writing config.
+
+Verify in your AI client:
+
+```text
+You:  apimapper_health
+LLM:  ✅ status: ok, platform: wordpress, version: 2.0.7
+```
+
+## Common tools
+
+A small set of high-leverage tools — the full 74-tool surface is
+[documented in detail in the bundled skill](./skills/apimapper/SKILL.md).
+
+| Tool | What it does |
+|------|--------------|
+| `apimapper_health` | Connectivity + auth probe. **Run this first.** |
+| `apimapper_onboarding` | Lists platform, existing flows, next-step suggestions. |
+| `apimapper_flow_setup_with_sources` | Composite: create flow + add sources + compile + publish. |
+| `apimapper_connection_list` | List connections (paginated, table-formatted). |
+| `apimapper_credential_create` | Add OAuth or Bearer credentials. |
+| `apimapper_oauth_authorize_begin` | Start an OAuth 2.0 PKCE flow. |
+| `apimapper_graph_preview` | Preview a flow's output without saving. |
+| `apimapper_library_catalog` | Browse pre-built connection templates. |
+| `apimapper_get_skill` | Fetch the bundled skill text on demand. |
+
+See [`skills/apimapper/SKILL.md`](./skills/apimapper/SKILL.md) for the
+canonical workflow guide, and
+[`skills/apimapper/reference/`](./skills/apimapper/reference/) for OAuth,
+Joomla, YOOtheme, and troubleshooting deep-dives.
+
+## Multi-platform: WordPress and Joomla
+
+Every tool routes through a platform abstraction that detects WordPress
+(`/wp-json/api-mapper/v1/*`) vs. Joomla (`/index.php?option=com_apimapper`)
+from the site URL and platform setting. You write the same prompt; the
+server speaks the right dialect — including the Joomla `com_ajax`
+envelope unwrap.
+
+## Multi-client
+
+Supported AI clients (auto-detected by the setup wizard):
+
+- **Claude Desktop** — DXT bundle or `~/Library/Application Support/Claude/`
+- **Claude Code** — `~/.claude.json`
+- **Cursor** — `~/.cursor/mcp.json` (or project-local `.cursor/mcp.json`)
+- **VS Code** — workspace `.vscode/settings.json` `mcp.servers`
+- **Cline** — VS Code extension settings
+- **Codex** — `~/.config/codex/mcp.json`
+- **ChatGPT Desktop** — when MCP support ships
+
+Both transports are supported: **stdio** (default, local install) and
+**HTTP + OAuth 2.0** (remote use, see [`docs/architecture.md`](./docs/architecture.md)).
+
+## Known issues
+
+### `npm install` requires `--legacy-peer-deps` (developer-only)
+
+**Most users don't need this.** If you install via:
+
+- `npx @wootsup/mcp setup` — no action required.
+- DXT bundle drag-and-drop into Claude Desktop — no action required.
+- Claude Desktop one-click install — no action required.
+
+…you can skip this section entirely. The `npx` and DXT paths ship a
+pre-resolved dependency tree (no peer-dep resolution happens at install
+or runtime), so the issue below cannot bite you.
+
+**For developers who clone this repo:**
+
+The dependency `@getimo/mcp-toolkit@1.0.0` declares a peer-dep on
+`@pipeline-studio/screenshot-capture` with the `workspace:*` protocol.
+That protocol is unresolvable outside the source monorepo, so a vanilla
+`npm install` fails with `EUNSUPPORTEDPROTOCOL`. Workaround:
+
+```sh
+npm install --legacy-peer-deps   # local dev
+npm ci      --legacy-peer-deps   # CI
+```
+
+Tracked in the customgraph repo — fix lands in `@getimo/mcp-toolkit@1.0.1`,
+at which point this section will be removed.
+
+## Troubleshooting
+
+See [`skills/apimapper/reference/troubleshooting.md`](./skills/apimapper/reference/troubleshooting.md).
+Common cases:
+
+- `403 invalid_token` → token expired or wrong site URL. Re-run setup.
+- `404` on every tool → plugin not installed or REST routes disabled.
+- Joomla `0` envelope → SEF/htaccess intercepting `com_ajax`; check
+  the reference doc.
+
+## Contributing
+
+PRs welcome. Source lives at
+[github.com/wootsup/api-mapper](https://github.com/wootsup/api-mapper)
+in `packages/apimapper-mcp/`. Run `npm test --workspace=@wootsup/mcp`
+before opening a PR; the cross-platform CI matrix
+([`apimapper-mcp-ci.yml`](../../.github/workflows/apimapper-mcp-ci.yml))
+re-runs on ubuntu, macOS, and windows.
+
+For the security disclosure process, see [`SECURITY.md`](./SECURITY.md).
+
+## License
+
+[MIT](./LICENSE) © 2026 WootsUp / getimo productions.
+
+## Links
+
+- **Homepage:** <https://wootsup.com/products/api-mapper>
+- **Plugin (WordPress + Joomla):** <https://wootsup.com/products/api-mapper>
+- **Docs:** <https://docs.wootsup.com>
+- **Issues:** <https://github.com/wootsup/api-mapper/issues>
+- **Architecture:** [`docs/architecture.md`](./docs/architecture.md)
+- **Security model:** [`docs/security.md`](./docs/security.md)
+- **Tools reference:** [`docs/tools.md`](./docs/tools.md)
+- **Changelog:** [`CHANGELOG.md`](./CHANGELOG.md)

package/SECURITY.md

@@ -0,0 +1,163 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Email **security@wootsup.com** with details. We aim to respond within
+72 hours.
+
+Please do not open public GitHub issues for security problems. If your
+report is accepted we will coordinate disclosure and credit you in the
+release notes (opt-in).
+
+PGP key: available on request.
+
+## Supported versions
+
+We patch security issues in the latest minor of `@wootsup/mcp`.
+During the `0.x` development line, only the most recent published
+version is supported.
+
+| Version | Supported |
+|---------|-----------|
+| `0.1.x` | ✅ active |
+| `< 0.1` | ❌ not yet published |
+
+When `1.0.0` lands, the previous minor (`0.x`) will receive critical
+security patches for 6 months.
+
+## Authentication model
+
+`@wootsup/mcp` uses a **Stripe-style HMAC-SHA256 token system**.
+
+### Token format
+
+```
+amk_<env>_<hex-key-id>.<base64url-signature>
+```
+
+- `amk_live_…` — production keys (full scope).
+- `amk_test_…` — sandbox keys (limited rate, no destructive ops).
+
+Tokens carry an embedded HMAC signed by a server-side signing key. The
+server validates the signature on every request before any business
+logic runs — there is no "user lookup by token string". This means a
+compromised replica of the database cannot mint valid tokens without
+also possessing the signing key.
+
+### Server-only signing key
+
+The signing key is generated on plugin install, stored once in:
+
+- **WordPress:** `wp_options.apimapper_signing_key` (autoload = false)
+- **Joomla:** `#__apimapper_settings.signing_key`
+
+It is **never** returned by any REST endpoint, never logged, never
+echoed in tool responses, and never written to the `@wootsup/mcp`
+keychain. The MCP server only sees the public token string.
+
+### Identity probe (anti-phishing)
+
+Before the setup wizard writes any config file, it issues a
+`GET /api-mapper/v1/mcp/identity` request. The server responds with:
+
+- the public `key_id`,
+- a `siteSignature` (HMAC over `key_id + site_url + nonce`),
+- and the user-visible site title.
+
+The wizard re-computes the signature using the public token payload and
+displays the site title + URL to the user for confirmation. A
+copy-pasted token from a malicious actor cannot pass this probe because
+the malicious server cannot forge the signature without the genuine
+signing key.
+
+### Scope semantics
+
+Tokens carry an embedded scope list:
+
+- `read` — list/get/inspect tools.
+- `write` — create/update/compile.
+- `destructive` — delete, reset-demo, license-deactivate.
+- `oauth` — credential creation + OAuth begin.
+
+Server-side enforcement runs **before** the platform abstraction layer.
+Frontend tool-listing additionally filters tools by available scopes,
+so an LLM with a read-only token never sees destructive tools in its
+tool-list (eliminates one class of confused-deputy risk).
+
+### No-secret-leak guarantees
+
+| Endpoint / Tool | Returns token? |
+|---|---|
+| `GET /mcp/keys` (list) | ❌ key IDs + scopes + last-used only. **Never** the token string. |
+| `POST /mcp/keys` (create) | ✅ **Only on creation.** Subsequent reads cannot retrieve it. |
+| `apimapper_credential_*` | ❌ Stored OAuth/Bearer creds are returned with values redacted (`***`). |
+| `apimapper_inspect_token` | Returns the **decoded payload** (key_id, scopes, env) but **not** the signature. |
+| `apimapper_settings_get` | Always strips `signing_key`, OAuth client secrets, and Brandfetch keys. |
+
+Server-side, the `CredentialSanitizer` runs on every response that
+could possibly contain a credential value — see
+[`src/modules/apimapper/credential-sanitizer.ts`](./src/modules/apimapper/credential-sanitizer.ts).
+Unit tests pin the redaction surface.
+
+### Token rotation
+
+- Rotate any time from **API Mapper → Connections → MCP Access →
+  Rotate**.
+- Old tokens revoke immediately. The MCP server returns
+  `403 invalid_token` on the next request; the user re-runs
+  `npx @wootsup/mcp setup`.
+- Rotation does **not** rotate the server-side signing key. The
+  signing key is rotated only on explicit "Reset all keys" — a
+  destructive op that requires re-issuing every active token.
+
+### Token revocation
+
+- Single token: **API Mapper → Connections → MCP Access → Revoke**.
+- All tokens: **API Mapper → Connections → MCP Access → Revoke all**
+  (also rotates the signing key).
+- Both operations are immediate; there is no caching of token validity
+  on the MCP server side.
+
+### Keychain fallback
+
+When OS keychain (`@napi-rs/keyring`) is unavailable (some Linux
+distros, CI containers), tokens fall back to a profile file at
+`~/.config/apimapper-mcp/profiles/<name>.json` with mode `0600`. The
+file is plain JSON containing the token string — readable by the user
+account only. If you operate in a hostile multi-user environment,
+**use the OS keychain path** (the default on macOS and Windows).
+
+### OAuth 2.0 (HTTP transport)
+
+When `@wootsup/mcp` runs in HTTP mode (`server-http.ts`), it acts as
+both an MCP server and an OAuth 2.0 authorization server with **PKCE
+required** (RFC 7636 S256). No implicit flow, no `code` grant without
+PKCE. Bearer tokens are bound to the issuing site URL and rejected if
+the `Origin` header differs.
+
+## Threat model summary
+
+| Threat | Mitigation |
+|---|---|
+| Token leak via logs | Sanitizer strips on every response path; tokens never logged. |
+| Token leak via tool output | List endpoints structurally exclude the token string. |
+| Replay across sites | HMAC includes site URL; cross-site replay fails sig check. |
+| Forged tokens | Server-side signing key never leaves the install. |
+| Phishing setup link | Identity probe + site-title confirmation in wizard. |
+| Confused-deputy / over-privileged LLM | Scope filter excludes destructive tools from token-restricted lists. |
+| Local-fs token theft (no keychain) | `0600` perms on profile file; keychain default on macOS/Windows. |
+
+See [`docs/security.md`](./docs/security.md) for the long-form threat
+model.
+
+## Disclosure timeline
+
+| Day | Action |
+|---|---|
+| 0 | Report received. Acknowledgement within 72h. |
+| 0-14 | Triage + reproduction + patch development. |
+| 14-30 | Coordinated patch release + security advisory. |
+| 30+ | Public disclosure (CVE if applicable). |
+
+For critical issues (active exploitation, supply chain) we will
+expedite and ship out-of-band.

package/dist/auth/keychain.d.ts

@@ -0,0 +1,47 @@
+export interface Keychain {
+    set(ref: string, value: string): Promise<void>;
+    get(ref: string): Promise<string | null>;
+    delete(ref: string): Promise<void>;
+}
+export declare class SystemKeychain implements Keychain {
+    private readonly service;
+    constructor(service?: string);
+    set(ref: string, value: string): Promise<void>;
+    get(ref: string): Promise<string | null>;
+    delete(ref: string): Promise<void>;
+}
+export declare class EncryptedFileKeychain implements Keychain {
+    private readonly dir;
+    private readonly vaultPath;
+    private readonly saltPath;
+    private cachedKey?;
+    private writeChain;
+    constructor(configDir: string);
+    private deriveKey;
+    private readVault;
+    private writeVault;
+    private encrypt;
+    private decrypt;
+    set(ref: string, value: string): Promise<void>;
+    get(ref: string): Promise<string | null>;
+    delete(ref: string): Promise<void>;
+}
+export interface CreateKeychainOptions {
+    /** Directory holding the encrypted vault + salt for the file fallback. */
+    configDir: string;
+    /**
+     * Override for tests — injecting a throwing or stub System ctor exercises
+     * the fallback / preference logic deterministically. Defaults to the real
+     * SystemKeychain.
+     */
+    systemKeychainCtor?: typeof SystemKeychain;
+    /** Service name passed to SystemKeychain. Defaults to "@wootsup/mcp". */
+    service?: string;
+    /**
+     * When false (default), the factory writes a one-line warning to stderr if
+     * it falls back to the file impl. Tests set this to true to keep output
+     * clean.
+     */
+    silent?: boolean;
+}
+export declare function createKeychain(opts: CreateKeychainOptions): Promise<Keychain>;