@wootsup/mcp 0.1.0-rc.1

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@wootsup/mcp",
+  "version": "0.1.0-rc.1",
+  "type": "module",
+  "description": "API Mapper MCP Server — multi-platform (WordPress/Joomla), multi-AI-client, Stripe-style auth, bundled skills",
+  "license": "MIT",
+  "author": "WootsUp <hello@wootsup.com>",
+  "homepage": "https://wootsup.com/products/api-mapper",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wootsup/api-mapper.git",
+    "directory": "packages/apimapper-mcp"
+  },
+  "bugs": "https://github.com/wootsup/api-mapper/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "api-mapper",
+    "wordpress",
+    "joomla",
+    "claude",
+    "chatgpt",
+    "cursor"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "apimapper-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "docs/",
+    "manifest.json",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js 2>/dev/null || true",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "start:http": "node dist/server-http.js",
+    "build:dxt": "node scripts/build-dxt.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@getimo/mcp-toolkit": "^1.0.0",
+    "@napi-rs/keyring": "^1.3.0",
+    "@clack/prompts": "^0.10.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/skills/apimapper/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: apimapper
+description: Use when working with API Mapper flows, connections, sources, credentials, or YOOtheme dynamic content on WordPress/Joomla — REST tools (`apimapper_*`), OAuth, Joomla com_ajax, Bearer auth.
+version: 0.1.0
+allowed-tools:
+  - apimapper_health
+  - apimapper_onboarding
+  - apimapper_get_skill
+---
+
+# API Mapper
+
+Bridge any REST API into YOOtheme via a saved flow (Source → Filter → Transform → Output). One server, one Bearer key, 74 MCP tools.
+
+## Quickstart
+
+1. **Set up MCP**
+   ```
+   npx -y @wootsup/mcp setup
+   ```
+   Interactive wizard: paste your MCP key, pick the AI client(s) to configure
+   (Claude Desktop, Cursor, Zed, Continue, Cline, Roo Code), wizard writes
+   the config files for you.
+
+2. **Generate a key**
+   - WordPress: click *API Mapper* in the WP admin menu to open the editor.
+     In the editor header (top-right), click the **⋮** (three-dot) menu →
+     *Settings*. In the Settings modal's left sidebar, click **MCP Access**
+     → *Generate new key*.
+   - Joomla: open *Components → API Mapper* — same editor loads. Use the
+     same **⋮** menu → *Settings* → **MCP Access** sidebar entry.
+
+3. **Verify + onboard**
+   ```
+   apimapper_health     → status: "ok"
+   apimapper_onboarding → lists platform, existing flows
+   ```
+
+## Common Tools
+
+| Tool | Use for |
+|------|---------|
+| `apimapper_connection_create` | New REST/OAuth source |
+| `apimapper_flow_setup_with_sources` | One-shot connection+flow+publish |
+| `apimapper_flow_compile` | Validate graph before publish |
+| `apimapper_library_activate` | Drop a featured template |
+| `apimapper_diagnose` | Triage 401/404/5xx |
+
+For topic docs: `apimapper_get_skill topic="..."` or read `skill://apimapper/<topic>`.
+
+## Common Pitfalls
+
+- **Source not in YOOtheme Builder** → flow is *saved* but not *published*. Click Publish. Published name (not "API Mapper") appears in YOOtheme Source dropdown.
+- **Joomla 404 on `/wp-json/...`** → Joomla wraps in `com_ajax`. See `apimapper_get_skill topic="joomla"`.
+- **OAuth expired** → use `apimapper_credential_link` to re-auth, NOT delete-and-recreate (loses `refresh_token`).
+
+Full docs: `wootsup.com/docs/mcp/`

package/skills/apimapper/reference/joomla.md

@@ -0,0 +1,85 @@
+# Joomla-Specific Gotchas
+
+API Mapper supports Joomla 5+ with feature parity to WordPress, but the transport differs. Most platform differences are absorbed by the MCP server — these notes cover the edge cases you may still hit.
+
+## Endpoint shape
+
+WordPress uses `wp-json` REST routes:
+```
+GET https://site.example/wp-json/api-mapper/v1/connections
+```
+
+Joomla wraps everything in a `com_ajax` envelope:
+```
+GET https://site.example/index.php?option=com_ajax&plugin=apimapper&format=json&task=connections.list
+```
+
+The MCP server detects platform automatically (via `apimapper_health`) and rewrites paths. You should never need to construct the URL by hand. If you do (debugging with `curl`), check `apimapper_platform_parity` for the current mapping.
+
+## Auth tiers
+
+Joomla has **three** auth paths, ordered by priority:
+
+### Tier 1 — Bearer fast-path
+A short-lived Bearer token signed by API Mapper. This is what `apimapper_credential_create` uses for the MCP-to-plugin call. Fast (no Joomla session bootstrap), works headless.
+
+Header: `Authorization: Bearer <token>`
+
+### Tier 2 — Joomla user session
+For requests originating in the admin UI (Property Panel REST calls). Cookie-based. The MCP server does NOT use this — it's relevant only when debugging admin-UI bugs.
+
+### Tier 3 — OAuth helper trampoline
+For OAuth callbacks (Google, Instagram, …). The OAuth provider POSTs to a public endpoint with a state token; API Mapper validates the state, swaps `code`→`access_token`, and stores into the credential record. The trampoline route is registered as a Joomla System Plugin event, NOT a com_ajax task — it must respond at a stable URL the provider can call back to.
+
+If OAuth keeps failing with `state_mismatch`, check that Joomla's `Update site` URL setting matches the OAuth callback URL configured at the provider. A common cause is `www.` vs apex mismatch.
+
+## com_ajax response envelope
+
+Joomla wraps successful responses:
+```json
+{ "success": true, "message": null, "messages": null, "data": [ <actual_response> ] }
+```
+
+Errors return `success: false` with a `message`. The MCP server unwraps `data[0]` automatically — but if you hit a third-party tool that calls the Joomla endpoint directly (e.g. a custom integration), you must unwrap.
+
+## Plugin location
+
+```
+/path/to/joomla/plugins/system/apimapper/
+├── apimapper.php             # System plugin entry — NOT api-mapper-joomla.php
+├── services/                 # Service registration
+├── src/                      # PSR-4 autoloaded
+└── language/
+```
+
+Note: the directory is `apimapper` (no hyphen), entry file is `apimapper.php`. This is a Joomla naming requirement (lowercase, no hyphens in plugin element names).
+
+## Common pitfalls
+
+1. **404 on a `/wp-json/...` URL** — you're hitting WordPress paths against a Joomla site. Re-resolve via the MCP, never hardcode paths.
+2. **`source.init` returning an array instead of an object** — Joomla System Plugin events can pass either. Add `is_object($source)` check at the boundary.
+3. **OAuth callback fails silently** — Joomla's URL rewriting can swallow query parameters. Verify `index.php?option=com_ajax&...` URLs work both with and without SEF rewriting enabled.
+4. **`com_ajax` cache** — Joomla caches the response by URL. Add `&_=` cache-bust during development, or disable Joomla cache plugin for `com_ajax` calls.
+5. **Bearer token rejected** — the token must be tied to a Joomla user with `apimapper.access` permission. Check Joomla → Users → Groups → Permissions.
+6. **`AdminCacheStore` invalidation seems no-op** — Joomla's object cache adapter differs from WP's. Use `apimapper_cache_invalidate` (not raw cache calls) to ensure both tiers flush.
+
+## Deployment
+
+Joomla extensions install as a `.zip` (system plugin). The MCP server bundles a single ZIP per release — `apimapper-mcp install` does not deploy the Joomla plugin; you install it via Joomla admin → Extensions → Install.
+
+To verify the plugin is loaded:
+```
+apimapper_health
+# → { platform: "joomla", version: "2.0.7", plugin: "enabled" }
+```
+
+If `plugin: "disabled"`, enable via Joomla admin → Extensions → Plugins → search "API Mapper".
+
+## Multi-platform development workflow
+
+When developing a fix:
+1. Test on WordPress (`/deploy-extensions wp`).
+2. Test on Joomla (`/deploy-extensions joomla`).
+3. Run `apimapper_platform_parity` to verify the same flow produces identical YOOtheme schemas on both platforms.
+
+Any divergence is a bug. Open an issue with the parity report attached.

package/skills/apimapper/reference/oauth.md

@@ -0,0 +1,94 @@
+# OAuth Sources
+
+Wiring OAuth-protected sources (Pexels API key, Google Sheets/Drive, Instagram Graph, Facebook Pages, Notion, Airtable, …) through API Mapper.
+
+## When to use OAuth vs static key
+
+| Auth shape | Examples | Credential type |
+|------------|----------|-----------------|
+| Static API key in header | Pexels, NewsAPI, OpenWeather | `bearer` or `apikey` |
+| OAuth2 authorization-code | Google Sheets/Drive, Instagram, Facebook, Notion | `oauth2_authcode` |
+| OAuth2 client-credentials | Spotify (catalog), some B2B APIs | `oauth2_clientcred` |
+| Personal access token | GitHub, GitLab, Airtable | `bearer` |
+
+If the API requires a user-consent screen and returns a `refresh_token`, you want `oauth2_authcode`. Everything else is `bearer`/`apikey`.
+
+## Wiring an OAuth source — full flow
+
+The two-step pattern is **always**: create credential → bind credential to connection. Credentials are reusable across connections.
+
+### Step 1 — Create the credential
+
+```
+apimapper_credential_create(
+  name="My Google Account",
+  type="oauth2_authcode",
+  provider="google",
+  scopes=["https://www.googleapis.com/auth/spreadsheets.readonly"]
+)
+```
+
+The tool returns a `credential_id` and an `authorize_url`. The caller (Claude / ChatGPT / Cursor) **must** surface the `authorize_url` to the user — the user clicks it, completes consent, the OAuth callback writes the `access_token` + `refresh_token` into the credential record.
+
+If you skip surfacing the URL, the credential will stay in `pending` state and every subsequent call will return 401.
+
+### Step 2 — Begin authorization (when refresh failed)
+
+If the credential is `expired` or the refresh token was revoked, re-trigger consent:
+
+```
+apimapper_oauth_authorize_begin(credential_id="cred_abc123")
+```
+
+Returns a new `authorize_url`. Same surface-it-to-the-user rule applies.
+
+### Step 3 — Create the connection bound to the credential
+
+```
+apimapper_connection_create(
+  name="Sheets — Marketing OKRs",
+  source_type="google_sheets",
+  credential_id="cred_abc123",
+  config={ "spreadsheet_id": "1AbC...", "range": "OKRs!A1:F100" }
+)
+```
+
+`source_type` selects the upstream driver (REST request shape, response normalizer, schema profiler). `config` is driver-specific.
+
+### Step 4 — Verify
+
+```
+apimapper_connection_test(connection_id="conn_xyz")
+```
+
+Returns one of:
+- `{ ok: true, sample: { ... } }` — green, you can build a flow on this
+- `{ ok: false, error: "401", hint: "credential expired → call apimapper_oauth_authorize_begin" }`
+- `{ ok: false, error: "scope_missing", hint: "credential lacks scope X → recreate with scopes=[...]" }`
+
+## Common pitfalls
+
+1. **Recreating credentials after expiry** — wipes the `refresh_token`. Always `apimapper_oauth_authorize_begin` first; only delete-and-recreate if the user revoked access on the provider side.
+2. **Hardcoding tokens into `connection.config.auth.token`** — bypasses the credential system, breaks rotation, fails on token expiry. Always use `credential_id`.
+3. **Forgetting to surface the `authorize_url`** — the user can't grant consent telepathically. Treat the URL as a required UI step, not a debug log line.
+4. **Scope drift** — provider adds new scopes (e.g. Google's `drive.readonly` split). Add them to the credential definition and re-authorize; pre-existing tokens lack them silently until a call returns 403.
+5. **Sharing a credential across users** — credentials are per-user (tied to the WordPress/Joomla user that created them). Cross-user share is not supported in 2.0.x.
+
+## Provider-specific notes
+
+- **Google** (Sheets/Drive/Calendar/Tasks) — needs `access_type=offline` and `prompt=consent` to issue a refresh token. The MCP server adds these automatically. If you bypass the MCP and craft the URL by hand, you must add them.
+- **Instagram Graph** — token expires every 60 days, refresh-token flow is non-standard (long-lived → exchange). API Mapper's refresh handler covers it; do not call the Meta endpoints directly.
+- **Notion / Airtable** — issue personal access tokens, not full OAuth. Use `bearer` credential type and paste the token; no `authorize_url` step.
+- **Pexels** — static API key; use `apikey` credential type. No consent screen.
+
+## Diagnose flow
+
+```
+apimapper_credential_get(credential_id="cred_abc123")
+# → { status: "expired", last_refresh_at: "2026-04-12T...", scopes: [...] }
+
+apimapper_diagnose(connection_id="conn_xyz")
+# → consolidates credential state + last connection_test + recent logs
+```
+
+For schema/transform issues (not auth issues), see `skill://apimapper/troubleshooting`.

package/skills/apimapper/reference/troubleshooting.md

@@ -0,0 +1,123 @@
+# Troubleshooting
+
+Diagnostic checklist when API Mapper tools return errors or flows misbehave. Work top-down — the most common causes are at the top.
+
+## Quick triage
+
+```
+apimapper_diagnose(connection_id="conn_xyz")   # one-call summary
+```
+
+`apimapper_diagnose` (Phase 8 composite tool) consolidates: credential state, last connection_test, recent error logs, license tier, schema profile. Use it FIRST before drilling into individual tools.
+
+If `apimapper_diagnose` is unavailable in your version, run the manual checks below.
+
+## HTTP status codes
+
+### 401 Unauthorized
+
+**Cause A — invalid Bearer**
+- `apimapper_health` returns `auth: "MISSING"` or `auth: "invalid"`.
+- Fix: regenerate the MCP access token in the plugin admin, update your client env.
+
+**Cause B — credential expired (OAuth flow)**
+- `apimapper_credential_get(credential_id="...")` shows `status: "expired"`.
+- Fix: `apimapper_oauth_authorize_begin(credential_id="...")` → surface URL to user. Do NOT delete + recreate.
+
+**Cause C — wrong scope**
+- Connection-test returns `scope_missing`.
+- Fix: recreate credential with extended `scopes=[...]`, re-authorize.
+
+### 403 Forbidden
+
+- License tier doesn't allow the requested action (e.g. 2nd connection on Free tier, JMESPath transform on Free tier).
+- Fix: `apimapper_license_status` to verify tier. Upgrade or stay within limits.
+
+### 404 Not Found
+
+**Cause A — endpoint not registered**
+- Plugin disabled or not installed.
+- Fix: `apimapper_health` → check `plugin: "enabled"`. On WP: Plugins → activate. On Joomla: Extensions → Plugins → enable.
+
+**Cause B — wrong platform path**
+- Hitting `/wp-json/...` on Joomla or `index.php?option=...` on WordPress.
+- Fix: let the MCP server resolve paths. If debugging manually, re-read `skill://apimapper/joomla`.
+
+**Cause C — resource ID typo**
+- `apimapper_flow_get(flow_id="flow_typo")` → 404.
+- Fix: `apimapper_flow_list` to find the correct ID.
+
+### 422 / 400 Validation error
+
+- The request body failed server-side validation.
+- The error response includes a `validation_errors` array with field-level detail.
+- Fix: check `connection.config` shape against `apimapper_local_source_schema` for the source type.
+
+### 429 Rate limited
+
+- Upstream API rate-limited the call.
+- API Mapper respects `Retry-After`; the breaker trips after repeated 429s.
+- Fix: wait the period given in the error response. For long-term: enable per-connection caching with `cacheTtl`.
+
+### 5xx Server error
+
+**Cause A — uncaught PHP exception**
+- Check plugin logs: WP → `wp-content/debug.log`, Joomla → `administrator/logs/`.
+- Sentry: search `wootsup` org → `api-mapper` project for the matching event.
+
+**Cause B — upstream API outage**
+- `apimapper_connection_test` against another known-good connection — if that also fails, it's network/server-side.
+- Status pages: check the upstream provider.
+
+**Cause C — schema introspection panic**
+- Often shows as `e is not iterable` in JS console or `Source not iterable` in PHP logs.
+- Cause: source returned a non-array where array was expected.
+- Fix: inspect the actual upstream response via `apimapper_connection_data(connection_id, raw=true)`. Add a Transform projection if needed.
+
+## Flow-specific issues
+
+### "Source not appearing in YOOtheme Builder"
+- Flow is saved but not **published**. See `skill://apimapper/yootheme` step 4.
+
+### "Source shows but fields are empty"
+- Field-name case mismatch. YOOtheme expects lowercase keys.
+- Fix: Transform projection should lowercase: `[*].{title: name, image: cover_url}`.
+
+### "Flow returns stale data"
+- Cache hit. Force refresh: `apimapper_connection_data(connection_id="...", forceRefresh=true)`.
+- Clear admin cache: `apimapper_cache_invalidate(scope="all")`.
+- Clear YOOtheme schema cache (sibling MCP): `yootheme_clear_cache`.
+
+### "Flow worked yesterday, broken today"
+- Most likely upstream API changed shape.
+- `apimapper_flow_detect_schema(flow_id="...")` — compare against the schema stored at last publish.
+- If drifted, re-publish (`apimapper_flow_full_recompile_publish`).
+
+## Credential-specific issues
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `pending` forever | User never clicked `authorize_url` | Re-surface URL. Don't recreate. |
+| `expired` after 1h | Refresh-token flow not wired | Check provider supports refresh; re-authorize with correct prompts |
+| `revoked` | User revoked access on provider side | Re-authorize from scratch (delete + create OK here) |
+| `error: invalid_scope` | Scope changed at provider | Recreate credential with new scopes |
+
+## Logs
+
+```
+# WordPress
+ssh deploy@dev.wootsup.com "tail -200 /var/www/dev.wootsup.com/wordpress/wp-content/debug.log | grep -i api-mapper"
+
+# Joomla
+ssh deploy@dev.wootsup.com "tail -200 /var/www/dev.wootsup.com/joomla/administrator/logs/everything.php"
+
+# Sentry (filtered)
+# → use sentry MCP: list_issues project=api-mapper
+```
+
+## When all else fails
+
+`apimapper_diagnose` first. If still stuck:
+1. Capture the full request + response (use the tool's `raw=true` flag where available).
+2. Note the platform, version (`apimapper_health`), license tier.
+3. Open a support ticket at `docs.wootsup.com/support` with that bundle.

package/skills/apimapper/reference/yootheme.md

@@ -0,0 +1,96 @@
+# Exposing API Mapper Sources to YOOtheme
+
+API Mapper sources show up in the YOOtheme Builder Source dropdown ONLY when a flow ends in a YOOtheme Output node and the flow is **published** (not just saved). This is the most common "source isn't appearing" cause.
+
+## The publish pipeline
+
+```
+Source ─► [Filter] ─► [Transform] ─► [Merge] ─► Output
+                                                  │
+                                                  ▼
+                                     ┌─────────────────────┐
+                                     │ YOOtheme Output (✓) │   → appears as YOOtheme Source
+                                     │ Shortcode Output    │   → [api_mapper id="..."] usable in posts
+                                     └─────────────────────┘
+```
+
+Both output types can coexist on the same flow.
+
+## Step-by-step
+
+1. **Build the flow** via `apimapper_flow_create` + `apimapper_app_add_node` calls, or one-shot via `apimapper_flow_setup_with_sources`.
+
+2. **Add a YOOtheme Output node** (NOT Shortcode):
+   ```
+   apimapper_app_configure_output(
+     flow_id="flow_abc",
+     output_type="yootheme",
+     source_name="Marketing Posts"
+   )
+   ```
+   The `source_name` is what appears in the YOOtheme Source dropdown. Keep it short and human-readable.
+
+3. **Compile** to validate schema + graph:
+   ```
+   apimapper_flow_compile(flow_id="flow_abc")
+   ```
+   This catches:
+   - Disconnected nodes
+   - Type drift between Transform output and Output input
+   - Missing required fields
+   - Filter expressions referencing fields that don't exist on the upstream
+
+4. **Publish**:
+   ```
+   apimapper_flow_full_recompile_publish(flow_id="flow_abc")
+   ```
+   This writes the flow into the YOOtheme Source registry and invalidates the YOOtheme schema cache.
+
+5. **Verify in YOOtheme Builder**:
+   - Open any YOOtheme page or template.
+   - Add a Grid / Slider / Dynamic element.
+   - "Source" dropdown → look for **the name you set in step 2** ("Marketing Posts"), NOT a "API Mapper" entry.
+
+## Schema for YOOtheme dynamic content
+
+YOOtheme reads the published flow's output schema (introspected by `apimapper_flow_detect_schema`). Each field on the schema becomes a mappable property in the YOOtheme element editor (title, image, link, date, …).
+
+To control which fields YOOtheme sees:
+- Use a `Transform` node with an explicit JMESPath/expression projection.
+- `[*].{title: name, image: cover.url, link: permalink}` is a typical canonical projection.
+- The Visual Expression Builder in the UI produces equivalent expressions; both end up in the same compiled flow.
+
+## Where YOOtheme features live (NOT in the flow)
+
+These belong in YOOtheme, not in API Mapper:
+
+| Feature | Where to configure |
+|---------|--------------------|
+| Sort order at render time | YOOtheme element → `filter_order` |
+| Filter at render time | YOOtheme element → `filter_reverse`, `filter` |
+| Slice / limit at render time | YOOtheme element → `limit`, `offset` |
+| Pagination | YOOtheme element + URL handling |
+| Per-page query overrides | YOOtheme element bindings (`source`) |
+
+API Mapper's job is to deliver typed clean JSON. The render-time slicing / sorting / filtering lives in YOOtheme. Don't reimplement it in a Transform node — it just bloats the flow and creates two truth sources.
+
+## Shortcode output (WordPress only)
+
+Same flow can ALSO emit a Shortcode output (`output_type="shortcode"`). Use this for:
+- Embedding in classic editor posts
+- Using outside YOOtheme (page builders, plugins)
+- Quick previews in admin
+
+Shortcode currently supports a subset of the YOOtheme render-time features. Document at `docs.wootsup.com/mcp/yootheme/shortcode`.
+
+## Common pitfalls
+
+1. **Save vs Publish** — saving stores the flow in `wp_options` (or Joomla equivalent) but does NOT register it as a YOOtheme Source. Always publish.
+2. **Looking for "API Mapper" in the dropdown** — wrong. Sources appear under the **flow's published source_name**.
+3. **Stale YOOtheme schema cache** — after a major schema change (Transform projection updated, new field added), clear YOOtheme cache: `yootheme_clear_cache` (sibling MCP) or via WP-Admin → YOOtheme → Settings → Clear Cache.
+4. **Republishing without recompile** — schema drift won't propagate. Use `apimapper_flow_full_recompile_publish`, not `apimapper_flow_publish`.
+5. **Dynamic content fields show as empty** — usually case sensitivity. YOOtheme expects field names lowercase; the Transform projection must produce lowercase keys. Field-Cards in the UI handle this automatically.
+
+## Multi-platform behaviour
+
+WordPress and Joomla produce identical YOOtheme schemas — the Source/Type registration goes through the same YOOtheme PHP API. But the underlying REST surface differs (see `skill://apimapper/joomla` for the Joomla envelope). Tools auto-detect the platform and route correctly.