@likerts/mcp 0.1.0

package/dist/main.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { LikertsClient } from './client.js';
+import { createServer } from './server.js';
+const client = new LikertsClient(process.env.LIKERTS_API_URL ?? 'http://127.0.0.1:8080', process.env.LIKERTS_TOKEN, process.env.LIKERTS_COLLECTION_TOKEN, fetch, process.env.LIKERTS_WORKSPACE_ID);
+await createServer(client).connect(new StdioServerTransport());

package/dist/remote-main.js

@@ -0,0 +1,9 @@
+import { createRemoteMcpHttpServer, remoteConfigFromEnvironment } from './remote.js';
+const port = Number.parseInt(process.env.LIKERTS_MCP_PORT ?? '8090', 10);
+if (!Number.isInteger(port) || port < 1 || port > 65535)
+    throw new Error('LIKERTS_MCP_PORT must be a valid TCP port');
+const host = process.env.LIKERTS_MCP_BIND_ADDRESS ?? '127.0.0.1';
+const server = createRemoteMcpHttpServer(remoteConfigFromEnvironment());
+server.listen(port, host, () => console.error(`Likerts remote MCP listening on ${host}:${port}`));
+for (const signal of ['SIGINT', 'SIGTERM'])
+    process.on(signal, () => server.close(() => process.exit(0)));

package/dist/remote.js

@@ -0,0 +1,160 @@
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { LikertsClient } from './client.js';
+import { createServer as createLikertsServer } from './server.js';
+const WORKSPACE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const MAX_BODY_BYTES = 64 * 1024;
+export function parseOrigin(value, name, allowLoopback = false) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${name} must be a valid origin`);
+    }
+    const loopback = allowLoopback && url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if ((!loopback && url.protocol !== 'https:') || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+        throw new Error(`${name} must be an HTTPS origin without credentials, path, query or fragment`);
+    }
+    return url;
+}
+export function remoteConfigFromEnvironment(env = process.env) {
+    const apiUrl = parseOrigin(env.LIKERTS_API_URL ?? '', 'LIKERTS_API_URL', true).origin;
+    const publicOrigin = parseOrigin(env.LIKERTS_MCP_PUBLIC_ORIGIN ?? '', 'LIKERTS_MCP_PUBLIC_ORIGIN', true).origin;
+    const authorizationServer = parseOrigin(env.LIKERTS_OIDC_ISSUER ?? '', 'LIKERTS_OIDC_ISSUER').origin;
+    const allowedOrigins = new Set((env.LIKERTS_MCP_ALLOWED_ORIGINS ?? '').split(',').filter(Boolean).map(value => parseOrigin(value.trim(), 'LIKERTS_MCP_ALLOWED_ORIGINS', true).origin));
+    if (!allowedOrigins.size)
+        throw new Error('LIKERTS_MCP_ALLOWED_ORIGINS must contain at least one trusted origin');
+    return { apiUrl, publicOrigin, authorizationServer, allowedOrigins };
+}
+function cors(req, res, config) {
+    const origin = req.headers.origin;
+    if (!origin)
+        return true;
+    if (!config.allowedOrigins.has(origin)) {
+        res.writeHead(403, { 'content-type': 'application/json', vary: 'Origin' }).end(JSON.stringify({ error: 'origin_not_allowed' }));
+        return false;
+    }
+    res.setHeader('access-control-allow-origin', origin);
+    res.setHeader('access-control-allow-credentials', 'true');
+    res.setHeader('access-control-expose-headers', 'Mcp-Session-Id, WWW-Authenticate');
+    res.setHeader('vary', 'Origin');
+    return true;
+}
+function metadata(config) {
+    return {
+        resource: config.publicOrigin,
+        authorization_servers: [config.authorizationServer],
+        bearer_methods_supported: ['header'],
+        scopes_supported: [
+            'surveys:read', 'surveys:write', 'collections:write', 'responses:read', 'responses:write',
+            'usage:read', 'exports:read', 'exports:write', 'identity:write',
+            'webhooks:read', 'webhooks:write'
+        ]
+    };
+}
+function challenge(config) {
+    return `Bearer resource_metadata="${config.publicOrigin}/.well-known/oauth-protected-resource"`;
+}
+async function body(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > MAX_BODY_BYTES)
+            throw new Error('payload_too_large');
+        chunks.push(bytes);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new Error('invalid_json');
+    }
+}
+export function createRemoteMcpHttpServer(config) {
+    // Validate trust-boundary configuration before opening a listening socket.
+    parseOrigin(config.apiUrl, 'LIKERTS_API_URL', true);
+    parseOrigin(config.publicOrigin, 'LIKERTS_MCP_PUBLIC_ORIGIN', true);
+    parseOrigin(config.authorizationServer, 'LIKERTS_OIDC_ISSUER');
+    return createServer(async (req, res) => {
+        if (req.url === '/health') {
+            if (req.method !== 'GET') {
+                res.writeHead(405, { allow: 'GET' }).end();
+                return;
+            }
+            res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' }).end(JSON.stringify({ service: 'likerts-mcp', status: 'ok' }));
+            return;
+        }
+        if (!cors(req, res, config))
+            return;
+        const url = new URL(req.url ?? '/', config.publicOrigin);
+        if (url.pathname === '/.well-known/oauth-protected-resource') {
+            if (req.method === 'OPTIONS') {
+                res.writeHead(204, {
+                    'access-control-allow-methods': 'GET, OPTIONS',
+                    'access-control-allow-headers': 'Authorization, Content-Type, MCP-Protocol-Version, MCP-Session-Id',
+                    'access-control-max-age': '600'
+                }).end();
+            }
+            else if (req.method === 'GET') {
+                res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'public, max-age=300' }).end(JSON.stringify(metadata(config)));
+            }
+            else
+                res.writeHead(405, { allow: 'GET, OPTIONS' }).end();
+            return;
+        }
+        const match = /^\/mcp\/([^/]+)$/.exec(url.pathname);
+        if (!match || !WORKSPACE.test(match[1])) {
+            res.writeHead(404, { 'content-type': 'application/json' }).end(JSON.stringify({ error: 'not_found' }));
+            return;
+        }
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204, {
+                'access-control-allow-methods': 'GET, POST, DELETE, OPTIONS',
+                'access-control-allow-headers': 'Authorization, Content-Type, MCP-Protocol-Version, MCP-Session-Id, X-Likerts-Collection-Token',
+                'access-control-max-age': '600'
+            }).end();
+            return;
+        }
+        const authorization = req.headers.authorization;
+        const token = authorization?.startsWith('Bearer ') ? authorization.slice(7) : '';
+        if (!token || token.trim() !== token || token.includes(' ')) {
+            res.writeHead(401, { 'content-type': 'application/json', 'www-authenticate': challenge(config) }).end(JSON.stringify({ error: 'unauthorized' }));
+            return;
+        }
+        if (!['GET', 'POST', 'DELETE'].includes(req.method ?? '')) {
+            res.writeHead(405, { allow: 'GET, POST, DELETE, OPTIONS' }).end();
+            return;
+        }
+        let parsed = undefined;
+        if (req.method === 'POST') {
+            try {
+                parsed = await body(req);
+            }
+            catch (error) {
+                const tooLarge = error instanceof Error && error.message === 'payload_too_large';
+                res.writeHead(tooLarge ? 413 : 400, { 'content-type': 'application/json' }).end(JSON.stringify({ error: tooLarge ? 'payload_too_large' : 'invalid_json' }));
+                return;
+            }
+        }
+        const collectionHeader = req.headers['x-likerts-collection-token'];
+        const collectionToken = typeof collectionHeader === 'string' && collectionHeader.length <= 512 ? collectionHeader : undefined;
+        const client = new LikertsClient(config.apiUrl, token, collectionToken, config.fetch ?? fetch, match[1]);
+        const server = createLikertsServer(client);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, parsed);
+        }
+        catch {
+            if (!res.headersSent)
+                res.writeHead(500, { 'content-type': 'application/json' }).end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: 'Internal server error' }, id: null }));
+        }
+        finally {
+            await transport.close();
+            await server.close();
+        }
+    });
+}

package/dist/resources.js

@@ -0,0 +1,8 @@
+import { existsSync, readFileSync } from 'node:fs';
+// npm archives carry their contracts beside the compiled code. A source checkout
+// and the existing container layout continue to read the canonical repository files.
+export function readContractResource(name) {
+    const bundled = new URL(`./data/${name}`, import.meta.url);
+    const checkout = new URL(name === 'capabilities.json' ? '../../capabilities.json' : '../../../contracts/openapi.json', import.meta.url);
+    return JSON.parse(readFileSync(existsSync(bundled) ? bundled : checkout, 'utf8'));
+}

package/dist/server.js

@@ -0,0 +1,35 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { capabilities, LikertsHttpError } from './client.js';
+import { operationContracts } from './contract.js';
+export function createServer(client) {
+    const server = new Server({ name: 'likerts', version: '0.1.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: capabilities.map(capability => ({
+            name: capability.name,
+            description: capability.description,
+            inputSchema: operationContracts.get(capability.name).inputSchema,
+            outputSchema: operationContracts.get(capability.name).outputSchema,
+            annotations: { readOnlyHint: capability.method === 'GET', destructiveHint: capability.method !== 'GET', openWorldHint: false }
+        })) }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const contract = operationContracts.get(request.params.name);
+        const failure = (code, message) => ({ isError: true, content: [{ type: 'text', text: JSON.stringify({ error: { code, message } }) }] });
+        if (!contract)
+            return failure('unknown_capability', 'Unknown Likerts capability');
+        const input = request.params.arguments ?? {};
+        if (!contract.validateInput(input))
+            return failure('invalid_request', 'Arguments do not match the published input schema');
+        try {
+            const data = await client.call(request.params.name, input);
+            if (!contract.validateOutput({ result: data }))
+                return failure('invalid_response', 'Server response does not match the published output schema');
+            return { content: [{ type: 'text', text: JSON.stringify(data) }], structuredContent: { result: data } };
+        }
+        catch (error) {
+            if (error instanceof LikertsHttpError)
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: { code: 'http_error', message: error.message, status: error.status, operation: error.operation } }) }] };
+            return failure('request_failed', 'Likerts request failed');
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@likerts/mcp",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && node scripts/package-data.mjs",
+    "test": "tsx --test test/*.test.ts",
+    "start": "node dist/main.js",
+    "start:remote": "node dist/remote-main.js",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "ajv": "8.20.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "description": "Typed MCP server for the free Likerts survey collection platform.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crosstabs/likerts.git",
+    "directory": "tools/mcp"
+  },
+  "homepage": "https://likerts.com/docs",
+  "bugs": {
+    "url": "https://github.com/crosstabs/likerts/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "likerts",
+    "surveys",
+    "feedback",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "likerts-mcp": "dist/main.js"
+  },
+  "mcpName": "io.github.crosstabs/likerts"
+}