{"_id":"402ai-mcp","name":"402ai-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"402ai-mcp","version":"1.0.0","description":"MCP server for 402ai.net - Lightning-paid OpenAI proxy tools","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"402ai-mcp":"dist/server.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"engines":{"node":">=18"},"scripts":{"clean":"rm -rf dist","build":"tsc -p tsconfig.json","dev":"tsx watch src/server.ts","start":"node dist/server.js","start:dev":"tsx src/server.ts","test":"vitest run","test:watch":"vitest","smoke:live":"tsx scripts/live-smoke.ts","prepack":"npm run clean && npm run build","prepublishOnly":"npm test"},"keywords":["mcp","402ai","openai","lightning","server"],"author":"","license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.27.0","zod":"^4.3.6"},"devDependencies":{"@types/node":"^25.3.0","tsx":"^4.21.0","typescript":"^5.9.3","undici":"^7.22.0","vitest":"^4.0.18"},"gitHead":"5e2225f6b7189e880a1c79cc019607512102f1ff","_id":"402ai-mcp@1.0.0","_nodeVersion":"25.5.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-3bxLs6pWwYnQL0p4EKFoNi6VX5XN/FDs7OVmx0NpHgPoveyRk39l8XkMZ7ruMh0feY6A68f2/eE852tod/fWpQ==","shasum":"d6f6c195951a871e63a93c5c3f23c53400b4f3b3","tarball":"https://registry.npmjs.org/402ai-mcp/-/402ai-mcp-1.0.0.tgz","fileCount":31,"unpackedSize":86420,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDkwL3/PAkXett5/q144OBTvkYPxST6qEiglNtCJT4pbAIgC3MWM7BTgGzrEHhWIt0mjH84gjgbalvy9ATh075m2Kk="}]},"_npmUser":{"name":"alittlebitofmoney","email":"burgesschen1990@gmail.com"},"directories":{},"maintainers":[{"name":"alittlebitofmoney","email":"burgesschen1990@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/402ai-mcp_1.0.0_1772683361539_0.3180402829835367"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T04:02:41.483Z","1.0.0":"2026-03-05T04:02:41.704Z","modified":"2026-03-05T04:02:41.885Z"},"maintainers":[{"name":"alittlebitofmoney","email":"burgesschen1990@gmail.com"}],"description":"MCP server for 402ai.net - Lightning-paid OpenAI proxy tools","keywords":["mcp","402ai","openai","lightning","server"],"license":"MIT","readme":"# 402ai-mcp\n\nMCP (Model Context Protocol) server for [402ai.net](https://402ai.net) - a Lightning-paid API proxy. Provides catalog-aware tools with compact/full profiles, bearer-first authentication, and dynamic tool refresh notifications.\n\n**Please update me when there are feature changes.**\n\n## Features\n\n- **Two Tool Profiles**: Compact (optimized for agents) or Full (comprehensive endpoint coverage)\n- **Catalog Synchronization**: Auto-fetches and tracks API catalog changes\n- **Bearer Token Auth**: First-class support for prepaid balance tokens\n- **Dynamic Tool Updates**: Notifies clients when catalog changes via MCP notifications\n- **Smart Consolidation**: Compact profile merges overlapping endpoints to reduce tool clutter\n- **TypeScript Native**: Full TypeScript implementation with type safety\n- **Comprehensive Testing**: Unit tests for catalog validation, deduplication, HTTP handling, and multipart uploads\n\n## Quick Start\n\n### Installation\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\n### Run via stdio\n\n```bash\nALBOM_BEARER_TOKEN=<your_token> npm start\n```\n\n### NPM Package\n\n```bash\nnpm install 402ai-mcp\n```\n\n## Configuration\n\nConfigure via environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `ALBOM_BASE_URL` | `https://402ai.net` | API base URL |\n| `ALBOM_BEARER_TOKEN` | _(none)_ | Prepaid balance token (strongly recommended) |\n| `ALBOM_TOOL_PROFILE` | `compact` | Tool profile: `compact` or `full` |\n| `ALBOM_INCLUDE_MODERATION` | `false` (compact), `true` (full) | Include moderation tools |\n| `ALBOM_INCLUDE_EMBEDDINGS` | `false` (compact), `true` (full) | Include embedding tools |\n| `ALBOM_INCLUDE_VIDEO` | `true` | Include video generation tools |\n| `ALBOM_ALLOW_RAW_TOOL` | `false` | Expose `albom_raw_call` tool (full profile only) |\n| `ALBOM_CATALOG_TTL_MS` | `300000` (5 min) | Catalog cache TTL |\n| `ALBOM_HTTP_TIMEOUT_MS` | `90000` (90 sec) | HTTP request timeout |\n| `ALBOM_MAX_RETRIES` | `2` | Max retry attempts for failed requests |\n| `ALBOM_MAX_UPLOAD_BYTES` | `26214400` (25 MB) | Max upload file size |\n\n## Tool Profiles\n\n### Compact Profile (Default)\n\nOptimized for AI agents with minimal tool ambiguity. Consolidates overlapping endpoints into semantic tools:\n\n| Tool | Purpose | Maps to Endpoint |\n|------|---------|------------------|\n| `albom_catalog_get` | Get live API catalog | `/api/v1/catalog` |\n| `albom_text_generate` | Generate text completions | `/v1/responses` |\n| `albom_image_generate` | Generate images | `/v1/images/generations` |\n| `albom_image_edit` | Edit images | `/v1/images/edits` |\n| `albom_audio_transcribe` | Transcribe audio (with optional translation) | `/v1/audio/transcriptions` (+ `/translations`) |\n| `albom_audio_speech` | Generate speech | `/v1/audio/speech` |\n| `albom_video_generate` | Generate videos (if enabled) | `/v1/video/generations` |\n| `albom_safety_moderate` | Content moderation (if enabled) | `/v1/moderations` |\n| `albom_embedding_create` | Create embeddings (if enabled) | `/v1/embeddings` |\n\n**Consolidations**:\n- Hides `/v1/chat/completions` in favor of `/v1/responses` (identical model sets)\n- Folds `/v1/audio/translations` into `albom_audio_transcribe` via boolean flag\n\n### Full Profile\n\nOne tool per catalog endpoint for comprehensive coverage:\n\n- `albom_openai_chat_completions`\n- `albom_openai_responses`\n- `albom_openai_images_generations`\n- `albom_openai_images_edits`\n- `albom_openai_images_variations`\n- `albom_openai_audio_speech`\n- `albom_openai_audio_transcriptions`\n- `albom_openai_audio_translations`\n- `albom_openai_embeddings`\n- `albom_openai_moderations`\n- `albom_openai_video_generations`\n- `albom_catalog_get`\n- `albom_raw_call` (if `ALBOM_ALLOW_RAW_TOOL=true`)\n\n## Authentication\n\n### Bearer Token (Recommended)\n\nSet `ALBOM_BEARER_TOKEN` to your prepaid balance token. All requests will use `Authorization: Bearer <token>`.\n\n**Get a token**:\n```bash\n# 1. Create topup invoice\ncurl -X POST https://402ai.net/api/v1/topup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"amount_sats\":1000}'\n\n# 2. Pay invoice with Lightning wallet, then claim\ncurl -X POST https://402ai.net/api/v1/topup/claim \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"preimage\":\"<hex-preimage>\"}'\n```\n\n### No Token (L402 Flow)\n\nWithout a token, calls will return `402 Payment Required` with a Lightning invoice. The MCP server will surface this as an error with payment details.\n\n## Usage Examples\n\n### With Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"402ai\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/402ai-mcp/dist/server.js\"],\n      \"env\": {\n        \"ALBOM_BEARER_TOKEN\": \"abl_your_token_here\",\n        \"ALBOM_TOOL_PROFILE\": \"compact\"\n      }\n    }\n  }\n}\n```\n\n### Programmatic Usage\n\n```typescript\nimport { createAlbomServer } from '402ai-mcp';\n\nconst server = createAlbomServer({\n  baseUrl: 'https://402ai.net',\n  bearerToken: process.env.ALBOM_BEARER_TOKEN,\n  toolProfile: 'compact'\n});\n\n// Start server\nawait server.run();\n```\n\n## Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Test\n\n```bash\nnpm test              # Run all tests\nnpm run test:watch    # Watch mode\n```\n\n### Dev Server\n\n```bash\nnpm run dev           # Watch and rebuild\nnpm run start:dev     # Run without build\n```\n\n### Smoke Test (Live API)\n\n```bash\nALBOM_BEARER_TOKEN=<token> npm run smoke:live\n```\n\n## Architecture\n\n### Core Modules\n\n- **`catalog.ts`**: Fetches and validates `/api/v1/catalog`, detects changes\n- **`config.ts`**: Environment variable configuration and validation\n- **`dedup.ts`**: Model set deduplication logic (Jaccard similarity)\n- **`httpClient.ts`**: HTTP client with retry logic, multipart support, bearer auth\n- **`tools/`**: Tool implementations for compact and full profiles\n- **`results.ts`**: Response normalization and error handling\n- **`uploads.ts`**: File upload handling (path and base64)\n- **`server.ts`**: MCP server implementation\n\n### Catalog Sync\n\n1. Fetches `/api/v1/catalog` on startup\n2. Caches for `ALBOM_CATALOG_TTL_MS`\n3. Periodically refreshes and compares\n4. Sends `notifications/tools/list_changed` if catalog changes\n5. Clients re-fetch tool definitions\n\n### Error Handling\n\nHTTP errors are normalized to MCP-friendly format:\n\n- `402 Payment Required`: Returns payment details (invoice, amount, expires_in)\n- `400 Bad Request`: Returns validation errors\n- `429 Rate Limited`: Returns retry-after info\n- `5xx Server Error`: Returns error message\n- Network errors: Automatic retry with exponential backoff\n\n## Testing\n\nTest suite covers:\n\n- Catalog validation and normalization\n- Model set deduplication (Jaccard similarity)\n- HTTP error normalization\n- Multipart upload encoding (path + base64)\n- Tool list change detection\n- Bearer token authentication\n- Retry logic\n\nRun tests:\n```bash\nnpm test\n```\n\n## Publishing\n\n```bash\n# 1. Build and test\nnpm run build\nnpm test\n\n# 2. Check package contents\nnpm pack --dry-run\n\n# 3. Publish\nnpm login\nnpm version patch  # or minor/major\nnpm publish --access public\n```\n\n## Project Structure\n\n```\n.\n├── src/\n│   ├── catalog.ts         # Catalog fetching and tracking\n│   ├── config.ts          # Environment configuration\n│   ├── dedup.ts           # Model set deduplication\n│   ├── httpClient.ts      # HTTP client with retries\n│   ├── server.ts          # MCP server implementation\n│   ├── tools/             # Tool implementations\n│   │   ├── compact.ts     # Compact profile tools\n│   │   ├── full.ts        # Full profile tools\n│   │   └── shared.ts      # Shared tool utilities\n│   ├── results.ts         # Response normalization\n│   ├── uploads.ts         # File upload handling\n│   ├── types.ts           # TypeScript types\n│   └── index.ts           # Public exports\n├── test/                  # Test suite\n├── scripts/               # Utility scripts\n├── dist/                  # Compiled output\n└── 402AI_MCP_IMPLEMENTATION_SPEC.md  # Design spec\n\nDocumentation:\n└── 402AI_MCP_IMPLEMENTATION_SPEC.md\n```\n\n## MCP Specification\n\nThis server implements [MCP spec revision 2025-11-25](https://modelcontextprotocol.io/specification).\n\nSupported features:\n- Tools capability\n- Notifications capability (`tools/list_changed`)\n- Tool annotations (`title`, `readOnlyHint`, `idempotentHint`)\n- stdio transport\n\n## License\n\nMIT - See LICENSE file.\n\n## Contributing\n\nSee WORKLOG.md for recent changes and development history.\n","readmeFilename":"README.md","_rev":"1-ffd144592b0aab204a283ba26e2cfc59"}