@blueprint-chart/mcp 0.1.0

package/dist/transports/http.js

@@ -0,0 +1,193 @@
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer as createHttpServer, } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { createServer } from '../server.js';
+class Semaphore {
+    available;
+    waiters = [];
+    constructor(max) {
+        this.available = max;
+    }
+    async acquire() {
+        if (this.available > 0) {
+            this.available -= 1;
+            return () => this.release();
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(() => {
+                this.available -= 1;
+                resolve(() => this.release());
+            });
+        });
+    }
+    release() {
+        this.available += 1;
+        const next = this.waiters.shift();
+        if (next) {
+            next();
+        }
+    }
+}
+class TokenBucketLimiter {
+    maxPerMinute;
+    buckets = new Map();
+    constructor(maxPerMinute) {
+        this.maxPerMinute = maxPerMinute;
+    }
+    consume(key) {
+        const now = Date.now();
+        const bucket = this.buckets.get(key) ?? { tokens: this.maxPerMinute, lastRefill: now };
+        const elapsed = now - bucket.lastRefill;
+        if (elapsed > 0) {
+            const refilled = (elapsed / 60_000) * this.maxPerMinute;
+            bucket.tokens = Math.min(this.maxPerMinute, bucket.tokens + refilled);
+            bucket.lastRefill = now;
+        }
+        if (bucket.tokens < 1) {
+            this.buckets.set(key, bucket);
+            return false;
+        }
+        bucket.tokens -= 1;
+        this.buckets.set(key, bucket);
+        return true;
+    }
+    prune() {
+        const cutoff = Date.now() - 5 * 60_000;
+        for (const [key, bucket] of this.buckets) {
+            if (bucket.lastRefill < cutoff) {
+                this.buckets.delete(key);
+            }
+        }
+    }
+}
+function getClientIp(req, trustProxy) {
+    if (trustProxy) {
+        const xff = req.headers['x-forwarded-for'];
+        if (typeof xff === 'string' && xff.length > 0) {
+            return xff.split(',')[0].trim();
+        }
+        if (Array.isArray(xff) && xff[0]) {
+            return xff[0].split(',')[0].trim();
+        }
+    }
+    return req.socket.remoteAddress ?? 'unknown';
+}
+function applyCors(res, origin, allowed) {
+    if (allowed === '*') {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+    }
+    else if (origin && allowed.includes(origin)) {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Vary', 'Origin');
+    }
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Mcp-Session-Id, Accept');
+    res.setHeader('Access-Control-Max-Age', '86400');
+}
+function logEvent(silent, fields) {
+    if (silent) {
+        return;
+    }
+    process.stderr.write(`${JSON.stringify({ ts: new Date().toISOString(), ...fields })}\n`);
+}
+function jsonResponse(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify(body));
+}
+export async function startHttp(opts) {
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    const server = createServer();
+    await server.connect(transport);
+    const allowedOrigins = opts.allowedOrigins ?? '*';
+    const trustProxy = opts.trustProxy ?? false;
+    const silent = opts.silent ?? false;
+    const semaphore = new Semaphore(opts.maxConcurrentRequests ?? 16);
+    const limiter = opts.rateLimitPerMinute && opts.rateLimitPerMinute > 0
+        ? new TokenBucketLimiter(opts.rateLimitPerMinute)
+        : undefined;
+    const pruneTimer = limiter ? setInterval(() => limiter.prune(), 60_000) : undefined;
+    if (pruneTimer && typeof pruneTimer.unref === 'function') {
+        pruneTimer.unref();
+    }
+    const httpServer = createHttpServer(async (req, res) => {
+        const started = Date.now();
+        const origin = req.headers.origin;
+        const ip = getClientIp(req, trustProxy);
+        applyCors(res, origin, allowedOrigins);
+        // CORS preflight
+        if (req.method === 'OPTIONS') {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+        // Health check (Railway / load-balancer liveness probe)
+        if (req.url === '/healthz' || req.url === '/health') {
+            jsonResponse(res, 200, { status: 'ok' });
+            return;
+        }
+        if (!req.url?.startsWith('/mcp')) {
+            jsonResponse(res, 404, { error: 'Not Found' });
+            return;
+        }
+        // Bearer token auth (off if MCP_AUTH_TOKEN not set)
+        if (opts.authToken) {
+            const auth = req.headers.authorization;
+            if (auth !== `Bearer ${opts.authToken}`) {
+                logEvent(silent, { event: 'auth_rejected', ip, method: req.method });
+                jsonResponse(res, 401, { error: 'Unauthorized' });
+                return;
+            }
+        }
+        // Per-IP rate limit
+        if (limiter && !limiter.consume(ip)) {
+            logEvent(silent, { event: 'rate_limited', ip });
+            res.setHeader('Retry-After', '60');
+            jsonResponse(res, 429, { error: 'Too Many Requests' });
+            return;
+        }
+        // Concurrency cap on POST (tool calls); GET streams unrestricted
+        const cap = req.method === 'POST';
+        const release = cap ? await semaphore.acquire() : undefined;
+        try {
+            await transport.handleRequest(req, res);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logEvent(silent, { event: 'transport_error', ip, method: req.method, message });
+            if (!res.headersSent) {
+                jsonResponse(res, 500, { error: 'Internal Server Error' });
+            }
+        }
+        finally {
+            release?.();
+            logEvent(silent, {
+                event: 'request',
+                ip,
+                method: req.method,
+                path: req.url,
+                status: res.statusCode,
+                durationMs: Date.now() - started,
+            });
+        }
+    });
+    await new Promise(resolve => httpServer.listen(opts.port, opts.host ?? '127.0.0.1', resolve));
+    const address = httpServer.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('http server has no port');
+    }
+    const url = `http://${opts.host ?? '127.0.0.1'}:${address.port}`;
+    return {
+        url,
+        close: async () => {
+            if (pruneTimer) {
+                clearInterval(pruneTimer);
+            }
+            await transport.close();
+            httpServer.closeAllConnections();
+            await new Promise((resolve, reject) => httpServer.close(err => (err ? reject(err) : resolve())));
+        },
+    };
+}

package/dist/transports/http.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transports/http.test.js

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { startHttp } from './http';
+async function withServer(opts, fn) {
+    const handle = await startHttp({ silent: true, ...opts });
+    try {
+        return await fn(handle.url);
+    }
+    finally {
+        await handle.close();
+    }
+}
+describe('http transport', () => {
+    it('responds to /mcp tools/list with status < 500', async () => {
+        await withServer({ port: 0 }, async (url) => {
+            const res = await fetch(`${url}/mcp`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'accept': 'application/json' },
+                body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),
+            });
+            expect(res.status).toBeLessThan(500);
+        });
+    });
+    it('serves /healthz returning {status:"ok"}', async () => {
+        await withServer({ port: 0 }, async (url) => {
+            const res = await fetch(`${url}/healthz`);
+            expect(res.status).toBe(200);
+            const body = await res.json();
+            expect(body.status).toBe('ok');
+        });
+    });
+    it('returns 404 for unknown paths', async () => {
+        await withServer({ port: 0 }, async (url) => {
+            const res = await fetch(`${url}/nope`);
+            expect(res.status).toBe(404);
+        });
+    });
+    it('handles CORS preflight (OPTIONS)', async () => {
+        await withServer({ port: 0 }, async (url) => {
+            const res = await fetch(`${url}/mcp`, { method: 'OPTIONS' });
+            expect(res.status).toBe(204);
+            expect(res.headers.get('access-control-allow-methods')).toMatch(/POST/);
+        });
+    });
+    it('rejects /mcp without token when authToken is set', async () => {
+        await withServer({ port: 0, authToken: 'secret' }, async (url) => {
+            const res = await fetch(`${url}/mcp`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'accept': 'application/json' },
+                body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),
+            });
+            expect(res.status).toBe(401);
+        });
+    });
+    it('accepts /mcp with correct bearer token', async () => {
+        await withServer({ port: 0, authToken: 'secret' }, async (url) => {
+            const res = await fetch(`${url}/mcp`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'accept': 'application/json',
+                    'authorization': 'Bearer secret',
+                },
+                body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),
+            });
+            expect(res.status).toBeLessThan(500);
+            expect(res.status).not.toBe(401);
+        });
+    });
+    it('rate-limits /mcp by IP', async () => {
+        await withServer({ port: 0, rateLimitPerMinute: 2 }, async (url) => {
+            const hit = async () => fetch(`${url}/mcp`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'accept': 'application/json' },
+                body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }),
+            });
+            const first = await hit();
+            const second = await hit();
+            const third = await hit();
+            expect(first.status).not.toBe(429);
+            expect(second.status).not.toBe(429);
+            expect(third.status).toBe(429);
+            expect(third.headers.get('retry-after')).toBe('60');
+        });
+    });
+});

package/dist/transports/stdio.d.ts

@@ -0,0 +1 @@
+export declare function startStdio(): Promise<void>;

package/dist/transports/stdio.js

@@ -0,0 +1,7 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from '../server';
+export async function startStdio() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@blueprint-chart/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for authoring Blueprint Chart .bpc files with LLMs.",
+  "license": "MIT",
+  "author": "pirhoo",
+  "type": "module",
+  "homepage": "https://github.com/blueprint-chart/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blueprint-chart/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/blueprint-chart/mcp/issues"
+  },
+  "bin": {
+    "blueprint-chart-mcp": "./bin/blueprint-chart-mcp.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:update-golden": "UPDATE_GOLDEN=1 vitest run test/golden",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@blueprint-chart/docs": "0.1.20",
+    "@blueprint-chart/lib": "0.1.19",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@napi-rs/canvas": "^0.1.71",
+    "@resvg/resvg-js": "^2.6.2",
+    "jsdom": "^26.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@stylistic/eslint-plugin": "^4.4.1",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^22.10.0",
+    "eslint": "^9.18.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.59.4",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}