{"_id":"@bpinternal/mcp-gen","_rev":"5-711f70d2fc5d3b0b179ab971c439a2d9","name":"@bpinternal/mcp-gen","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@bpinternal/mcp-gen","version":"0.1.0","_id":"@bpinternal/mcp-gen@0.1.0","maintainers":[{"name":"allardy","email":"yann.allard1@gmail.com"},{"name":"davidvitora","email":"david.vitora@gmail.com"},{"name":"michael.masson","email":"michael.masson@botpress.com"},{"name":"franklevasseur","email":"francois.levasseur@botpress.com"},{"name":"chsir17","email":"sirois.christophe@gmail.com"},{"name":"slvnperron","email":"slvn.perron@gmail.com"},{"name":"botpress-cloud-ops","email":"cloud-ops@botpress.com"}],"bin":{"mcp-gen":"dist/index.js"},"dist":{"shasum":"0cb93b07840e8575817ac444c399aefd959ee984","tarball":"https://registry.npmjs.org/@bpinternal/mcp-gen/-/mcp-gen-0.1.0.tgz","fileCount":44,"integrity":"sha512-r6kjFA1AuVIC2e1p+A5HWN2CHm6OxtcjUjEfWZAZa/Q27ixih/REt8hh36dTEpjjWVYUocC8OnZv8vhtb4SkfQ==","signatures":[{"sig":"MEUCIEeSftorKnfbFs5EZliSQLZcLmtPKo5Zm0i5sCq9E6zzAiEAl3smA4n1UH73U8hKl1327qzLu08u5CpSLvV0aX+8sQc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":5219167},"main":"dist/api.js","type":"module","types":"dist/api.d.ts","exports":{".":{"types":"./dist/api.d.ts","import":"./dist/api.js"},"./cli":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./config":{"types":"./dist/config-manager.d.ts","import":"./dist/config-manager.js"}},"gitHead":"b04028597bee436a0af32dd9618f6b0bb01ff4a1","scripts":{"dev":"tsx src/index.ts","test":"vitest","build":"tsup src/index.ts src/api.ts src/config-manager.ts src/validators.ts --format esm --dts --clean","start":"tsx src/index.ts","watch":"tsup src/index.ts --format esm --dts --watch","generate":"node dist/index.js","test:run":"vitest run","check:type":"tsc --noEmit","test:watch":"vitest watch","check:format":"prettier --check .","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm build && pnpm check:type"},"_npmUser":{"name":"botpress-cloud-ops","email":"cloud-ops@botpress.com"},"_npmVersion":"10.9.2","description":"Generate Botpress integrations from MCP servers","directories":{},"_nodeVersion":"22.17.0","dependencies":{"commander":"^14.0.3","node-fetch":"^3.3.2","eventsource":"^4.1.0","@botpress/cli":"^5.5.4","@botpress/sdk":"^5.4.1","@bpinternal/zui":"^1.3.3","zod-to-json-schema":"^3.22.4","@modelcontextprotocol/sdk":"^1.26.0","@apidevtools/json-schema-ref-parser":"^15.2.2"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.12.4","devDependencies":{"tsx":"^4.19.0","tsup":"^8.0.1","vitest":"^2.1.8","prettier":"^3.8.1","typescript":"^5.7.2","@types/node":"^22.15.0","@vitest/coverage-v8":"^2.1.8"},"_npmOperationalInternal":{"tmp":"tmp/mcp-gen_0.1.0_1770949607077_0.7656480960465404","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bpinternal/mcp-gen","version":"0.1.1","_id":"@bpinternal/mcp-gen@0.1.1","maintainers":[{"name":"allardy","email":"yann.allard1@gmail.com"},{"name":"davidvitora","email":"david.vitora@gmail.com"},{"name":"michael.masson","email":"michael.masson@botpress.com"},{"name":"franklevasseur","email":"francois.levasseur@botpress.com"},{"name":"chsir17","email":"sirois.christophe@gmail.com"},{"name":"slvnperron","email":"slvn.perron@gmail.com"},{"name":"botpress-cloud-ops","email":"cloud-ops@botpress.com"}],"homepage":"https://github.com/botpress/packages#readme","bugs":{"url":"https://github.com/botpress/packages/issues"},"bin":{"mcp-gen":"dist/index.js"},"dist":{"shasum":"f8d0242c8a012756f8fd314e186df48d57ce4d8f","tarball":"https://registry.npmjs.org/@bpinternal/mcp-gen/-/mcp-gen-0.1.1.tgz","fileCount":44,"integrity":"sha512-KQ3rKIZSqPVrpUhV94MlthZBk8ZN8DIDhKA/fVaePJLTGJt2L+Nf8buEw4p8Oz6fknfCotzQ61O2aTSjMFrugA==","signatures":[{"sig":"MEYCIQD2D7FD0Plbli4f1ZHoSDDsB5VCoG9IeIRV8FSkuzuhcAIhAP1tfBQB4/+9iY963v0xx0iEEUHXtkDkAq1R6NyuA/Qy","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@bpinternal%2fmcp-gen@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":5219249},"main":"dist/api.js","type":"module","types":"dist/api.d.ts","exports":{".":{"types":"./dist/api.d.ts","import":"./dist/api.js"},"./cli":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./config":{"types":"./dist/config-manager.d.ts","import":"./dist/config-manager.js"}},"gitHead":"c7991079ce37bf6da09a41c4933be96bd4af4d0e","scripts":{"dev":"tsx src/index.ts","test":"vitest","build":"tsup src/index.ts src/api.ts src/config-manager.ts src/validators.ts --format esm --dts --clean","start":"tsx src/index.ts","watch":"tsup src/index.ts --format esm --dts --watch","generate":"node dist/index.js","test:run":"vitest run","check:type":"tsc --noEmit","test:watch":"vitest watch","check:format":"prettier --check .","test:coverage":"vitest run --coverage","prepublishOnly":"pnpm build && pnpm check:type"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:a01bb145-8890-418b-8a12-06dcaa491360"}},"repository":{"url":"git+https://github.com/botpress/packages.git"},"_npmVersion":"11.10.0","description":"Generate Botpress integrations from MCP servers","directories":{},"_nodeVersion":"22.17.0","dependencies":{"commander":"^14.0.3","node-fetch":"^3.3.2","eventsource":"^4.1.0","@botpress/cli":"^5.5.4","@botpress/sdk":"^5.4.1","@bpinternal/zui":"^1.3.3","zod-to-json-schema":"^3.22.4","@modelcontextprotocol/sdk":"^1.26.0","@apidevtools/json-schema-ref-parser":"^15.2.2"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.12.4","devDependencies":{"tsx":"^4.19.0","tsup":"^8.0.1","vitest":"^2.1.8","prettier":"^3.8.1","typescript":"^5.7.2","@types/node":"^22.15.0","@vitest/coverage-v8":"^2.1.8"},"_npmOperationalInternal":{"tmp":"tmp/mcp-gen_0.1.1_1770950364728_0.5451198660464434","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-02-13T02:26:46.945Z","modified":"2026-09-02T19:11:38.561Z","0.1.0":"2026-02-13T02:26:47.308Z","0.1.1":"2026-02-13T02:39:24.897Z"},"bugs":{"url":"https://github.com/botpress/packages/issues"},"homepage":"https://github.com/botpress/packages#readme","repository":{"url":"git+https://github.com/botpress/packages.git"},"description":"Generate Botpress integrations from MCP servers","maintainers":[{"email":"yann.allard1@gmail.com","name":"allardy"},{"email":"michael.masson@botpress.com","name":"michael.masson"},{"email":"slvn.perron@gmail.com","name":"slvnperron"},{"email":"xavier.hamel.protic@gmail.com","name":"xavierhamel"},{"email":"cloud-ops@botpress.com","name":"botpress-cloud-ops"}],"readme":"# MCP Integration Generator\n\nGenerate Botpress integrations from Model Context Protocol (MCP) servers using a proxy pattern.\n\n## Quick Start\n\n```bash\n# Install and build\npnpm install && pnpm build\n\n# Initialize new integration\nmcp-gen init github-mcp https://api.github.com/mcp \\\n  --output ./output \\\n  --auth ghp_your_github_token \\\n  --save\n\n# Update tools from saved config\nmcp-gen update --tools\n```\n\n## Features\n\n- **Automatic Tool Discovery**: Connects to any MCP server and discovers available tools\n- **Proxy Pattern**: Single shared implementation for all tools\n- **Multiple Transports**: HTTP (default) and SSE support\n- **Type-Safe**: Generates Zui (Zod) schemas from JSON Schema with comprehensive validation\n- **Scoped Updates**: Refresh tools, definition, or code independently\n- **Config Persistence**: Claude-compatible mcp-server.json format\n\n## CLI Commands\n\n### `init` - Create New Integration\n\n```bash\nmcp-gen init <name> <url> --output <dir> [options]\n```\n\n**Options:**\n\n- `--output, -o <dir>` - Output directory (required)\n- `--transport, -t <type>` - Transport: `http` (default) or `sse`\n- `--auth, -a <token>` - Authorization token (shortcut for Bearer header)\n- `--header, -H <header>` - Add custom header (format: \"Key: Value\", repeatable)\n- `--save` - Save config to mcp-server.json for easy updates\n- `--config-file <filename>` - Custom config filename (default: mcp-server.json)\n\n**Environment Variable:**\n\n- `MCP_AUTH_TOKEN` - Auto-loads as Authorization Bearer token\n\n**Examples:**\n\n```bash\n# Basic usage with shortcut auth\nmcp-gen init github-mcp https://api.github.com/mcp \\\n  --output ./output \\\n  --auth ghp_your_github_token \\\n  --save\n\n# With custom headers\nmcp-gen init slack-mcp https://slack.com/api/mcp \\\n  --output ./integration \\\n  --header \"Authorization: Bearer xoxb-token\" \\\n  --header \"X-API-Key: key123\" \\\n  --save\n\n# Using environment variable\nexport MCP_AUTH_TOKEN=ghp_your_github_token\nmcp-gen init github-mcp https://api.github.com/mcp \\\n  --output ./output \\\n  --save\n```\n\n### `update` - Update Existing Integration\n\n```bash\nmcp-gen update [output] [options]\n```\n\nUpdates an existing integration from saved mcp-server.json. No scope flags = update all. Use flags to select what to update.\n\n**Scope Flags:**\n\n- `--tools` - Update action-definitions, actions, and hub.md\n- `--definition` - Update integration.definition.ts\n- `--code` - Update src/index.ts and src/mcp-proxy.ts\n\nWhen no scope flags are provided, all scopes are updated (equivalent to `--tools --definition --code`), except `src/index.ts` which is only regenerated with `--code` to preserve your customizations.\n\n**Override Options:**\n\n- `--url, -u <url>` - Override MCP server URL (instead of what's in config)\n- `--transport, -t <type>` - Override transport type\n- `--auth, -a <token>` - Override authorization token\n- `--header, -H <header>` - Override request headers\n- `--config-file <filename>` - Custom config filename (default: mcp-server.json)\n\n**Examples:**\n\n```bash\n# Update just tools (most common)\nmcp-gen update --tools\n\n# Auto-detect config, update everything\nmcp-gen update\n\n# Specify directory\nmcp-gen update ./my-integration --tools\n\n# Override auth token for this run\nmcp-gen update --auth bp_pat_new_token --tools\n\n# Override the MCP server URL\nmcp-gen update --url https://new-api.example.com/mcp --tools\n\n# Update only the proxy code\nmcp-gen update --code\n```\n\n## Config File Format\n\nThe `--save` flag creates a `mcp-server.json` file (Claude-compatible):\n\n```json\n{\n  \"name\": \"github-mcp\",\n  \"url\": \"https://api.github.com/mcp\",\n  \"type\": \"http\",\n  \"headers\": {\n    \"Authorization\": \"Bearer ghp_your_github_token\"\n  }\n}\n```\n\nThis enables easy updates without re-entering credentials.\n\n## Generated Structure\n\n```\noutput/\n├── package.json\n├── tsconfig.json\n├── .gitignore\n├── integration.definition.ts    # Integration metadata\n├── hub.md                        # Documentation\n├── icon.svg                      # Generic MCP icon (customize)\n├── action-definitions/             # One file per tool\n│   ├── index.ts\n│   ├── tool1.ts\n│   └── tool2.ts\n└── src/\n    ├── index.ts                  # Integration entry point\n    ├── actions.ts                # Action router (MCP tool mappings)\n    └── mcp-proxy.ts              # Shared MCP proxy implementation\n```\n\n### Proxy Pattern\n\nThe integration uses a shared proxy implementation that routes all tool calls through a single codebase:\n\n- Single point of configuration\n- Easy maintenance (change once, affects all)\n- Consistent error handling and authentication\n- Clean separation between definitions and implementation\n\n## Programmatic API\n\n```typescript\nimport { generateIntegration } from '@bpinternal/mcp-gen'\n\nawait generateIntegration({\n  integrationName: 'github-mcp',\n  mcpServerUrl: 'https://api.github.com/mcp',\n  outputDir: './output',\n  transport: 'http',\n  headers: {\n    Authorization: 'Bearer ghp_your_github_token'\n  },\n  saveConfig: true,\n  updateMode: false\n})\n```\n\n### With Config Auto-Loading\n\n```typescript\nimport { generateIntegrationWithConfig } from '@bpinternal/mcp-gen'\n\n// Uses saved config from mcp-server.json\nawait generateIntegrationWithConfig({\n  outputDir: './my-integration',\n  updateMode: true // Only update tool definitions\n})\n```\n\n### TypeScript Types\n\n```typescript\nimport type { GeneratorOptions, TransportType, McpServerConfig } from '@bpinternal/mcp-gen'\n```\n\n## Validation\n\nAll inputs are validated using Zod schemas:\n\n- **Integration names**: Lowercase alphanumeric + hyphens, max 50 chars\n- **URLs**: Valid HTTP/HTTPS URLs only\n- **Paths**: Path traversal prevention\n- **Headers**: RFC 7230 compliant header names and non-empty values\n- **Transport types**: Only `http` or `sse` allowed\n\n## Development\n\n```bash\n# Run from source (no build needed)\npnpm dev init github-mcp https://api.github.com/mcp --output ./output\n\n# Watch mode (auto-rebuild)\npnpm watch\n\n# Build\npnpm build\n\n# Type check\npnpm check:type\n\n# Install globally\npnpm link --global\nmcp-gen --help\n```\n\n## Next Steps After Generation\n\n1. **Install dependencies**: `cd output && pnpm install`\n2. **Build integration**: `pnpm bpbuild`\n3. **Customize icon** (optional): Replace `icon.svg`\n4. **Update documentation**: Enhance `hub.md`\n5. **Test in Botpress**: Deploy and test actions\n\n## Updating When MCP Server Changes\n\n```bash\n# Most common: just refresh tools\nmcp-gen update --tools\n\n# Or update everything\nmcp-gen update\n\n# Review changes\ngit diff\n\n# Rebuild\npnpm bpbuild\n```\n\nThe update command:\n\n- Refreshes tool definitions, actions, and hub.md (`--tools`)\n- Updates integration.definition.ts (`--definition`)\n- Updates src/mcp-proxy.ts and src/index.ts (`--code`)\n- Uses saved credentials from mcp-server.json\n\n## Troubleshooting\n\n### Connection Errors\n\n- Ensure MCP server is running\n- Verify URL is correct\n- Check authentication token is valid\n\n### Validation Errors\n\n- Integration name must be lowercase with hyphens only\n- URLs must use http:// or https:// protocol\n- Headers must follow \"Key: Value\" format\n\n### Build Errors\n\n- Run `pnpm install` in generated directory\n- Verify all dependencies are available\n- Check TypeScript configuration\n\n## Transport Types\n\n- **HTTP** (default): Streamable HTTP transport - best for most MCP servers\n- **SSE**: Server-Sent Events transport - for SSE-only servers\n\nSpecify with `--transport sse` if needed.\n\n## Architecture\n\nThe generator creates integrations using a **proxy pattern**:\n\n1. **Definitions Layer** (`action-definitions/`): What each tool does (schemas, descriptions)\n2. **Actions Layer** (`src/actions.ts`): Maps each action to its MCP tool call via the proxy\n3. **Implementation Layer** (`src/mcp-proxy.ts`): How to call MCP tools (single shared implementation)\n4. **Integration Layer** (`src/index.ts`): Entry point that wires everything together\n\n### Tool Name Sanitization\n\nTool names are automatically converted to proper camelCase for Botpress:\n\n| MCP Tool Name                 | Action Name                   | MCP Call Uses |\n| ----------------------------- | ----------------------------- | ------------- |\n| `dbGetRDSPerformanceInsights` | `dbGetRdsPerformanceInsights` | Original name |\n| `get-user-profile`            | `getUserProfile`              | Original name |\n| `create_workspace`            | `createWorkspace`             | Original name |\n\nThe proxy always uses the original tool name when calling the MCP server.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}