{"_id":"@aipp/mcp-server","name":"@aipp/mcp-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aipp/mcp-server","version":"0.1.0","description":"Official Model Context Protocol (MCP) Server for AIPP — Monetize APIs, automations, and digital tools with HTTP 402 micro-payments","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"aipp-mcp":"dist/bin/aipp-mcp.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./bin/aipp-mcp":"./dist/bin/aipp-mcp.js"},"publishConfig":{"access":"public"},"type":"module","scripts":{"build":"tsc","prepublishOnly":"npm run build","start":"node dist/bin/aipp-mcp.js","dev":"tsx src/bin/aipp-mcp.ts","test":"vitest run"},"engines":{"node":">=18.0.0"},"keywords":["mcp","model-context-protocol","aipp","l402","x402","lightning","usdc","payments","agents","ai"],"author":{"name":"AIPP Team","email":"info@aipp.dev"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aipp-key/aippdev.git","directory":"packages/mcp-server"},"bugs":{"url":"https://github.com/aipp-key/aippdev/issues"},"homepage":"https://aipp.dev","dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","zod":"^3.25.76"},"devDependencies":{"@types/node":"^20.12.7","tsx":"^4.7.2","typescript":"^5.4.5","vitest":"^4.1.10"},"gitHead":"bc5b6b7d6abdb7f0bd2b68e88738a2d57f7aad3f","_id":"@aipp/mcp-server@0.1.0","_nodeVersion":"24.12.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-BSVC+YQ5tGmwmShlakjnWzpKZ8a+vsqi278c5XaKbrWyoUuG0O47nrOeCHcxdrhzFUugY257wNpqsSHMlUHOug==","shasum":"15c541d381daa7abf0e825d1789caa107580ee5a","tarball":"https://registry.npmjs.org/@aipp/mcp-server/-/mcp-server-0.1.0.tgz","fileCount":39,"unpackedSize":108608,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCID+MAFafbzUM9bjpTPiIkwikMOjf1Qs66pRlhE0I2FaVAiB1TBOTT4MUHutJ4BMuW1edm/yN33/6KJXpcNeEvTZUBw=="}]},"_npmUser":{"name":"aipp","email":"farukucal@gmail.com"},"directories":{},"maintainers":[{"name":"aipp","email":"farukucal@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.1.0_1788354772538_0.32141986749993157"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T13:12:52.333Z","0.1.0":"2026-09-02T13:12:52.670Z","modified":"2026-09-02T13:12:52.908Z"},"maintainers":[{"name":"aipp","email":"farukucal@gmail.com"}],"description":"Official Model Context Protocol (MCP) Server for AIPP — Monetize APIs, automations, and digital tools with HTTP 402 micro-payments","homepage":"https://aipp.dev","keywords":["mcp","model-context-protocol","aipp","l402","x402","lightning","usdc","payments","agents","ai"],"repository":{"type":"git","url":"git+https://github.com/aipp-key/aippdev.git","directory":"packages/mcp-server"},"author":{"name":"AIPP Team","email":"info@aipp.dev"},"bugs":{"url":"https://github.com/aipp-key/aippdev/issues"},"license":"MIT","readme":"# @aipp/mcp-server\n\nOfficial Model Context Protocol (MCP) Server for **[AIPP](https://aipp.dev)** — Monetize APIs, automations, prompt inferences, and digital tools with HTTP 402 micro-payments directly to your Bitcoin Lightning or Base USDC wallet.\n\n---\n\n## ⚡ Overview\n\n`@aipp/mcp-server` allows AI assistants and developer agents (Claude Desktop, Cursor, Antigravity, Cline, etc.) to discover, create, and verify AIPP Smart Tags via the standard Model Context Protocol over `stdio`.\n\n### Included Tools:\n- 🏷️ **`aipp_create_smart_tag`**: Create a priced capability, protected link, file download, AI capability, booking, or API endpoint for a merchant ($0.01 to $100.00 USD).\n- 📋 **`aipp_get_tag_manifest`**: Inspect verified machine-readable pricing, payment rails (Lightning L402 / Base USDC x402), and endpoints for any Smart Tag.\n\n### What it DOES NOT DO:\n- ❌ Does **not** hold funds or maintain custodial accounts (AIPP is strictly non-custodial and direct-to-wallet).\n- ❌ Does **not** trigger merchant payouts or fund transfers.\n- ❌ Does **not** perform mutations during read queries.\n- ❌ Does **not** submit on-chain payment proofs or execute arbitrary URL requests (SSRF protected).\n- ❌ Does **not** expose API keys in tool parameters, output schemas, or error logs.\n\n> **Parking Lot Note on Payment Status / Reconciliation:**\n> A dedicated `payment-status` / invoice reconciliation tool will only be considered in a future release after a strictly read-only, non-state-mutating status query endpoint is introduced into the core AIPP backend.\n\n---\n\n## 🚀 Quick Start (Client Configuration)\n\nAdd the following to your MCP client configuration file:\n\n### Claude Desktop / Cursor / Antigravity (`mcpServers` config)\n\n```json\n{\n  \"mcpServers\": {\n    \"aipp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aipp/mcp-server\"],\n      \"env\": {\n        \"AIPP_API_KEY\": \"aipp_merch_your_api_key_here\",\n        \"AIPP_BASE_URL\": \"https://aipp.dev\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** To obtain a free merchant API key, visit [aipp.dev/studio.html](https://aipp.dev/studio.html) or register your Lightning/USDC address.\n\n---\n\n## ⚙️ Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `AIPP_API_KEY` | Optional* | `undefined` | Merchant API key required for `aipp_create_smart_tag`. Read-only tools work without an API key. |\n| `AIPP_BASE_URL` | Optional | `https://aipp.dev` | Base gateway URL. Must be HTTPS in production (localhost is permitted for local development). |\n| `AIPP_REQUEST_TIMEOUT_MS` | Optional | `15000` | HTTP request timeout in milliseconds (500 - 120,000 ms). |\n| `AIPP_MAX_RESPONSE_BYTES` | Optional | `1048576` (1MB) | Maximum allowable upstream response payload size (1KB - 10MB). Enforced on stream reader. |\n| `AIPP_MAX_REDIRECT_HOPS` | Optional | `3` | Maximum allowable GET redirect hops (0 - 10). |\n\n---\n\n## 🛠️ Tool Catalog & Schemas\n\nAll tools provide dual output:\n1. Canonical **`structuredContent`** validated against explicit Zod output schemas.\n2. Backwards-compatible formatted JSON text in `content`.\n\n### 1. `aipp_create_smart_tag`\n* **Type:** State-changing (Requires `AIPP_API_KEY`)\n* **Purpose:** Create a priced capability, URL paywall, file download, AI capability, booking, or API endpoint.\n* **Example User Intent:**\n  > *\"Charge 100 sats ($0.05) before someone can access my private dataset link.\"*\n  > *\"Create an AIPP Smart Tag for my analysis API costing $0.10 per request.\"*\n\n**Input Parameters:**\n- `title` *(string, required)*: Descriptive title for the tag (1-100 characters).\n- `amount_usd` *(number, required)*: Price in USD between `$0.01` and `$100.00`.\n- `capability_type` *(enum, optional)*: `\"link\" | \"file\" | \"ai\" | \"booking\" | \"api\"` (default: `\"link\"`).\n- `redirect_url` *(string, optional)*: Target URL released upon valid payment proof.\n- `description` *(string, optional)*: Technical summary of the capability.\n- `idempotency_key` *(string, optional)*: Client token to prevent duplicate tag creation.\n\n---\n\n### 2. `aipp_get_tag_manifest`\n* **Type:** Read-only (Public, No API key needed)\n* **Purpose:** Retrieve verified pricing, accepted rails, and checkout challenge metadata for a tag.\n* **Example User Intent:**\n  > *\"What are the payment rails and price for AIPP tag 'demo'?\"*\n  > *\"Show me the HTTP 402 manifest for tag 'p_8a92b3c1'.\"*\n\n**Input Parameters:**\n- `tag_id` *(string, required)*: Alphanumeric tag identifier (e.g. `\"demo\"` or `\"p_123456789abc\"`).\n\n---\n\n## 🔒 Security Model\n\n1. **SSRF & Redirect Protection:** The client enforces `redirect: 'manual'` and validates redirect hops against same-origin rules. Redirects on POST/mutations are rejected fail-closed. Redirects to off-origin hosts, private IPs, loopback, or cloud metadata endpoints (`169.254.169.254`) are rejected fail-closed.\n2. **Protected Headers:** Custom headers cannot override protected security headers (`X-Api-Key`, `Authorization`, `Host`, `Content-Length`, `User-Agent`). Public requests never send API credentials.\n3. **Leak-Free Stream Bounding:** Responses are read with an enforced byte counter and a single abort listener. Any response exceeding `maxResponseBytes` is immediately cancelled.\n4. **Secret Redaction:** `AIPP_API_KEY` is loaded exclusively from the process environment. Any accidental appearance in errors is automatically scrubbed by the sanitizer.\n5. **Official Package Scope:** Distributed under the official `@aipp` npm organization scope with strict zero-secret tarball filtering.\n\n---\n\n## 🚦 Error Handling & Codes\n\nWhen an operation fails, the tool returns structured, machine-readable errors:\n\n| Code | Description | Retryable |\n|---|---|---|\n| `AUTH_MISSING` | `AIPP_API_KEY` is not configured in the client environment. | No |\n| `AUTH_INVALID` | Provided API key was rejected by the upstream gateway. | No |\n| `VALIDATION_ERROR` | Tool input failed strict Zod schema validation. | No |\n| `NOT_FOUND` | Requested Smart Tag does not exist. | No |\n| `UPSTREAM_INVALID_RESPONSE` | Upstream gateway returned malformed JSON or missing required fields. | No |\n| `RESPONSE_TOO_LARGE` | Upstream response payload exceeded maximum byte limit. | No |\n| `UNSAFE_REDIRECT` | Upstream returned a disallowed cross-origin, mutation, or metadata redirect. | No |\n| `RATE_LIMITED` | Gateway rate limit exceeded. | Yes (wait 30s) |\n| `UPSTREAM_TIMEOUT` | Gateway did not respond within the configured timeout. | Yes |\n| `UPSTREAM_UNAVAILABLE` | Gateway is unreachable or returning 5xx errors. | Yes |\n\n---\n\n## 🧪 Development & Testing\n\n```bash\n# Install dependencies\nnpm ci\n\n# Run typecheck and unit tests\nnpm test\n\n# Run TypeScript build\nnpm run build\n```\n\n---\n\n## 📄 License\n\nMIT © [AIPP](https://aipp.dev)\n","readmeFilename":"README.md","_rev":"1-61fb3ea9eb34b7927a3bc1fb108afe56"}