# vyne-mcp

MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server for
[vyne](https://vyne.finance) — a Zapier-style automation engine for Solana
DeFi. Vynes are workflows of typed **leaves**; on-chain events, cron
schedules, webhooks, or manual fires drive multi-step pipelines that execute
through a per-user agent wallet bounded by per-vyne signing policies.


- **32 tools** covering discovery (`find_leaves`, `get_capabilities`,
  `check_supported`), authoring (`compile_vyne`, `plant_vyne`, `test_vyne`),
  ad-hoc reads (`query_leaf`), and run inspection (`get_runs`, `tail_run`) —
  each with zod input schemas, MCP tool annotations
  (`readOnlyHint`/`destructiveHint`/…), structured errors with actionable
  `next_steps[]`, and list truncation with continuation hints.
- **11 resources** (`vyne://wallet`, `vyne://capabilities`,
  `vyne://leaves/{id}`, …) for lazy reads that don't burn tool-call slots.
- **10 guided prompts** (`build_vyne`, `diagnose_run`, `fund_wallet`, …)
  encoding the canonical authoring loop so LLM clients follow the same
  guardrails every time. See [PROMPTS.md](PROMPTS.md).
- **Output redaction** ([src/redact.ts](src/redact.ts)) — bot tokens, webhook
  URLs, and OAuth secrets stored in user workflow configs are masked before
  they reach the model's context.

## Transports

- **stdio** — for Claude Desktop and other local clients. The API key sits
  in `VYNE_API_KEY` for the lifetime of the subprocess:
  `node dist/index.js stdio`
- **Streamable HTTP** — for hosted clients (claude.ai custom connectors).
  The key arrives as `Authorization: Bearer <key>` per request; sessions are
  tracked via `Mcp-Session-Id` per the MCP spec. Includes RFC 9728 protected
  resource metadata + OAuth redirect shims so OAuth-aware clients discover
  the API's authorization server automatically.

## Running

```bash
npm install
npm run build

# HTTP transport (default, port 3100)
VYNE_API_URL=<your-api-base-url> npm start

# stdio transport (Claude Desktop)
VYNE_API_URL=<your-api-base-url> VYNE_API_KEY=sk_live_… npm run start:stdio
```

See [.env.example](.env.example) for every knob (toolset filtering,
read-only mode, CORS allowlist, logging).

### Claude Desktop config

```json
{
  "mcpServers": {
    "vyne": {
      "command": "node",
      "args": ["/path/to/vyne-mcp/dist/index.js", "stdio"],
      "env": {
        "VYNE_API_URL": "<your-api-base-url>",
        "VYNE_API_KEY": "sk_live_…"
      }
    }
  }
}
```

## Scope of this repository

This repo contains the MCP server only. The vyne REST API it talks to —
the workflow engine, leaf manifests, compiler/preflight pipeline, signing
infrastructure, and curated on-chain address registry — is a separate,
closed-source service. Consequently:

- `src/vendor/` holds small utilities inlined from internal packages
  (structured logging, `.env` loading, token-amount formatting). The
  client-side token resolver ([src/vendor/funding.ts](src/vendor/funding.ts))
  is trimmed to well-known public mints; authoritative funding math comes
  from the API (`estimate_vyne_funding` / `preflight_vyne`).
- You need access to a running vyne API instance (and an API key or OAuth
  token issued by it) for the server to do anything useful.

## Development

```bash
npm run dev        # tsx watch, HTTP transport
npm run typecheck
npm test           # vitest (redaction unit tests)
```