@likerts/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Likerts contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# Likerts MCP server
+
+Operate the free, MIT-licensed Likerts survey platform from an MCP client. The server exposes the same typed operations and authorization boundaries as the HTTP API and CLI.
+
+The hosted server is listed in the [official MCP registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.crosstabs%2Flikerts/versions/latest) as `io.github.crosstabs/likerts`. Configure your workspace ID and scoped service credential in your MCP client. The listing does not make workspace data public.
+
+## Install
+
+Install a published version from npm:
+
+```sh
+npm install --global @likerts/mcp
+```
+
+Alternatively, download the MCP tarball from the [community release](https://github.com/crosstabs/likerts/releases) and run `npm install --global /absolute/path/to/the-mcp-package.tgz`. Node.js 22 or newer is required.
+
+Configure your MCP client to run `likerts-mcp` over stdio. Set `LIKERTS_API_URL` to your API origin and supply a scoped `LIKERTS_TOKEN` through your environment or secret manager. The local API defaults to `http://127.0.0.1:8080`. Collection operations use `LIKERTS_COLLECTION_TOKEN` separately; keep management credentials out of embedded apps and tool arguments.
+
+For a source checkout:
+
+```sh
+npm ci --prefix tools/mcp
+npm run build --prefix tools/mcp
+node tools/mcp/dist/main.js
+```
+
+Launch the command from an MCP client; stdout is reserved for protocol messages. Authentication and permission checks remain enforced by your API.
+
+## Remote connection
+
+The optional hosted endpoint is `https://likerts-mcp.onrender.com/mcp/{workspaceId}`. It requires the workspace's scoped service credential. Self-hosters use their own remote host.
+
+[Setup for Codex and Claude](https://github.com/crosstabs/likerts/blob/main/tools/README.md) · [Quickstart](https://likerts.com/docs) · [API reference](https://likerts.com/docs/api)

package/dist/client.js

@@ -0,0 +1,76 @@
+import { readContractResource } from './resources.js';
+export const capabilities = readContractResource('capabilities.json');
+export class LikertsHttpError extends Error {
+    operation;
+    status;
+    constructor(operation, status) {
+        super(`Likerts ${operation} failed (HTTP ${status})`);
+        this.operation = operation;
+        this.status = status;
+    }
+}
+export class LikertsClient {
+    managementToken;
+    collectionToken;
+    transport;
+    workspaceId;
+    base;
+    constructor(baseUrl, managementToken, collectionToken, transport = fetch, workspaceId) {
+        this.managementToken = managementToken;
+        this.collectionToken = collectionToken;
+        this.transport = transport;
+        this.workspaceId = workspaceId;
+        try {
+            this.base = new URL(baseUrl);
+        }
+        catch {
+            throw new Error('LIKERTS_API_URL must be a valid origin');
+        }
+        if (this.base.username || this.base.password || this.base.search || this.base.hash || this.base.pathname !== '/')
+            throw new Error('LIKERTS_API_URL must be an origin without credentials, path, query or fragment');
+        if (this.base.protocol !== 'https:' && !(this.base.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(this.base.hostname)))
+            throw new Error('HTTPS is required except on loopback');
+    }
+    async call(name, input) {
+        const operation = capabilities.find(c => c.name === name);
+        if (!operation)
+            throw new Error('Unknown capability');
+        const token = operation.auth === 'management' ? this.managementToken : this.collectionToken;
+        if (!token)
+            throw new Error(`Missing ${operation.auth} credential`);
+        let path = operation.path;
+        const body = { ...input };
+        if (path.includes('{id}')) {
+            if (typeof input.id !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(input.id))
+                throw new Error('Invalid resource ID');
+            path = path.replace('{id}', encodeURIComponent(input.id));
+            delete body.id;
+        }
+        const url = new URL(path, this.base);
+        if (operation.method === 'GET') {
+            for (const [key, value] of Object.entries(body)) {
+                if (value === undefined)
+                    continue;
+                if (!['string', 'number', 'boolean'].includes(typeof value))
+                    throw new Error('Invalid query input');
+                url.searchParams.set(key, String(value));
+            }
+        }
+        const response = await this.transport(url, {
+            method: operation.method, redirect: 'error', signal: AbortSignal.timeout(30_000),
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', ...(operation.auth === 'management' && this.workspaceId ? { 'x-likerts-workspace': this.workspaceId } : {}) },
+            ...(operation.method === 'GET' ? {} : { body: JSON.stringify(body) })
+        });
+        // Do not echo upstream bodies: malformed servers may return credentials or HTML.
+        if (!response.ok)
+            throw new LikertsHttpError(name, response.status);
+        if (response.status === 204)
+            return {};
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new Error('Server returned invalid JSON');
+        }
+    }
+}

package/dist/contract.js

@@ -0,0 +1,68 @@
+import { readContractResource } from './resources.js';
+import { createRequire } from 'node:module';
+import { capabilities } from './client.js';
+const spec = readContractResource('openapi.json');
+const Ajv = createRequire(import.meta.url)('ajv/dist/2020').default;
+const ajv = new Ajv({ strict: false, allErrors: true });
+ajv.addFormat('uuid', /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+ajv.addFormat('date-time', (value) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && !Number.isNaN(Date.parse(value)));
+ajv.addFormat('uri', (value) => { try {
+    new URL(value);
+    return true;
+}
+catch {
+    return false;
+} });
+// Inline local references so MCP clients need no external schema resolver.
+function inline(value, ancestors = []) {
+    if (Array.isArray(value))
+        return value.map(item => inline(item, ancestors));
+    if (value && typeof value === 'object') {
+        if (value.$ref) {
+            if (!value.$ref.startsWith('#/components/schemas/') || ancestors.includes(value.$ref))
+                throw new Error('Unsupported or recursive contract reference');
+            const schema = spec.components.schemas[value.$ref.split('/').at(-1)];
+            if (!schema)
+                throw new Error('Missing contract schema');
+            return inline(schema, [...ancestors, value.$ref]);
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, inline(item, ancestors)]));
+    }
+    return value;
+}
+export const operationContracts = new Map();
+for (const capability of capabilities) {
+    const operation = spec.paths[capability.path]?.[capability.method.toLowerCase()];
+    if (operation?.operationId !== capability.name)
+        throw new Error(`Missing OpenAPI capability ${capability.name}`);
+    const body = inline(operation.requestBody?.content?.['application/json']?.schema ?? { type: 'object', properties: {}, additionalProperties: false });
+    if (body.type !== 'object')
+        throw new Error('Capability body must be an object');
+    const parameters = operation.parameters ?? [];
+    const properties = { ...body.properties };
+    const required = [...(body.required ?? [])];
+    for (const parameter of parameters) {
+        if (!['path', 'query'].includes(parameter.in))
+            continue;
+        if (parameter.name in properties)
+            throw new Error('Ambiguous body/path/query input field');
+        properties[parameter.name] = inline(parameter.schema);
+        if (parameter.required)
+            required.push(parameter.name);
+    }
+    const parameterCount = parameters.filter(p => ['path', 'query'].includes(p.in) && p.required).length;
+    const inputSchema = { ...body, type: 'object', properties, required, additionalProperties: false };
+    if (inputSchema.minProperties !== undefined)
+        inputSchema.minProperties += parameterCount;
+    if (inputSchema.maxProperties !== undefined)
+        inputSchema.maxProperties += parameterCount;
+    const successes = Object.entries(operation.responses).filter(([status]) => /^2\d\d$/.test(status));
+    if (successes.length !== 1)
+        throw new Error('Capability must have one explicit success response');
+    const [status, response] = successes[0];
+    const resultSchema = status === '204' ? { type: 'object', additionalProperties: false } : inline(response.content?.['application/json']?.schema);
+    if (!resultSchema)
+        throw new Error('Missing successful output schema');
+    const outputSchema = { type: 'object', properties: { result: resultSchema }, required: ['result'], additionalProperties: false };
+    operationContracts.set(capability.name, { inputSchema, outputSchema, validateInput: ajv.compile(inputSchema), validateOutput: ajv.compile(outputSchema) });
+}

package/dist/data/capabilities.json

@@ -0,0 +1,266 @@
+[
+  {
+    "name": "surveys_create",
+    "method": "POST",
+    "path": "/v1/surveys",
+    "description": "Create a survey draft idempotently; identical retries return the original draft.",
+    "input": "survey",
+    "auth": "management"
+  },
+  {
+    "name": "surveys_list",
+    "method": "GET",
+    "path": "/v1/surveys",
+    "description": "List workspace surveys.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "surveys_update",
+    "method": "PUT",
+    "path": "/v1/surveys/{id}",
+    "description": "Update a draft using its current revision.",
+    "input": "update",
+    "auth": "management"
+  },
+  {
+    "name": "surveys_publish",
+    "method": "POST",
+    "path": "/v1/surveys/{id}/publish",
+    "description": "Publish an immutable version only when every customer-declared SDK installation supports its schema version.",
+    "input": "publish",
+    "auth": "management"
+  },
+  {
+    "name": "collections_create",
+    "method": "POST",
+    "path": "/v1/collections",
+    "description": "Create an immutable embedded collection only when every declared SDK installation supports the bound schema version. Identical retries return the original submission credential; handle it as a secret.",
+    "input": "collection",
+    "auth": "management"
+  },
+  {
+    "name": "collections_update",
+    "method": "PATCH",
+    "path": "/v1/collections/{id}",
+    "description": "Open or close collection acceptance, or irreversibly revoke its credential.",
+    "input": "acceptance",
+    "auth": "management"
+  },
+  {
+    "name": "collections_security_update",
+    "method": "PUT",
+    "path": "/v1/collections/{id}/security",
+    "description": "Configure exact browser origins and a per-collection request rate. Origins are browser policy, not authentication.",
+    "input": "collection_security",
+    "auth": "management"
+  },
+  {
+    "name": "collections_get",
+    "method": "GET",
+    "path": "/v1/collections/{id}",
+    "description": "Fetch the immutable respondent configuration using a collection credential.",
+    "input": "id",
+    "auth": "collection"
+  },
+  {
+    "name": "responses_submit",
+    "method": "POST",
+    "path": "/v1/collections/{id}/responses",
+    "description": "Submit a completed response. Accepted responses are counted for observability and are never metered or charged. Reuse the same idempotency key only for identical retries.",
+    "input": "submission",
+    "auth": "collection"
+  },
+  {
+    "name": "responses_list",
+    "method": "GET",
+    "path": "/v1/responses",
+    "description": "Retrieve one stable snapshot page of workspace responses, optionally filtered by collection and acceptance time. Continue with nextCursor.",
+    "input": "response_list",
+    "auth": "management"
+  },
+  {
+    "name": "responses_delete",
+    "method": "DELETE",
+    "path": "/v1/responses/{id}",
+    "description": "Erase one response's raw answers and metadata while preserving its minimal retry receipt and usage entry.",
+    "input": "id",
+    "auth": "management"
+  },
+  {
+    "name": "exports_create",
+    "method": "POST",
+    "path": "/v1/exports",
+    "description": "Create or idempotently retry a bounded asynchronous CSV or JSON response export.",
+    "input": "export",
+    "auth": "management"
+  },
+  {
+    "name": "exports_get",
+    "method": "GET",
+    "path": "/v1/exports/{id}",
+    "description": "Read an export job's status and stable schema manifest.",
+    "input": "id",
+    "auth": "management"
+  },
+  {
+    "name": "exports_download",
+    "method": "GET",
+    "path": "/v1/exports/{id}/download",
+    "description": "Download a ready export as authenticated base64 content before its 24-hour expiry.",
+    "input": "id",
+    "auth": "management"
+  },
+  {
+    "name": "exports_revoke",
+    "method": "DELETE",
+    "path": "/v1/exports/{id}",
+    "description": "Irreversibly revoke export access and remove its stored object.",
+    "input": "id",
+    "auth": "management"
+  },
+  {
+    "name": "retention_run",
+    "method": "POST",
+    "path": "/v1/retention",
+    "description": "Run one bounded raw-response and expired-export retention batch for the workspace.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "workspace_delete",
+    "method": "DELETE",
+    "path": "/v1/workspace",
+    "description": "Erase and tombstone the current workspace account, revoke capabilities and remove export objects.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "memberships_list",
+    "method": "GET",
+    "path": "/v1/memberships",
+    "description": "List current workspace memberships. Owner access is required.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "memberships_put",
+    "method": "PUT",
+    "path": "/v1/memberships",
+    "description": "Grant or replace a workspace membership role. Owner access is required.",
+    "input": "membership",
+    "auth": "management"
+  },
+  {
+    "name": "memberships_revoke",
+    "method": "POST",
+    "path": "/v1/memberships/revoke",
+    "description": "Revoke a workspace membership immediately. Owner access is required.",
+    "input": "subject",
+    "auth": "management"
+  },
+  {
+    "name": "service_credentials_list",
+    "method": "GET",
+    "path": "/v1/service-credentials",
+    "description": "List service credential metadata without secret values. Owner access is required.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "service_credentials_create",
+    "method": "POST",
+    "path": "/v1/service-credentials",
+    "description": "Issue a scoped service credential. Its token is returned exactly once.",
+    "input": "service_credential",
+    "auth": "management"
+  },
+  {
+    "name": "service_credentials_revoke",
+    "method": "DELETE",
+    "path": "/v1/service-credentials/{id}",
+    "description": "Irreversibly revoke a service credential.",
+    "input": "id",
+    "auth": "management"
+  },
+  {
+    "name": "oauth_grants_create",
+    "method": "POST",
+    "path": "/v1/oauth-grants",
+    "description": "Persist consent as a tenant, subject, client, audience and scope-bound OAuth grant.",
+    "input": "oauth_grant",
+    "auth": "management"
+  },
+  {
+    "name": "oauth_grants_revoke",
+    "method": "DELETE",
+    "path": "/v1/oauth-grants/{id}",
+    "description": "Irreversibly revoke an OAuth grant for subsequent requests.",
+    "input": "id",
+    "auth": "management"
+  },
+  {
+    "name": "usage_get",
+    "method": "GET",
+    "path": "/v1/usage",
+    "description": "Retrieve accepted-response usage.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "webhook_endpoints_create",
+    "method": "POST",
+    "path": "/v1/webhook-endpoints",
+    "description": "Creates disabled. Install the returned signing secret on your receiver, then explicitly enable. An identical idempotency retry reconstructs the original generation.",
+    "input": "WebhookEndpointInput",
+    "auth": "management"
+  },
+  {
+    "name": "webhook_endpoints_list",
+    "method": "GET",
+    "path": "/v1/webhook-endpoints",
+    "description": "Lists up to 100 workspace endpoints, including revoked entries. Signing secrets are never listed.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "webhook_endpoints_update",
+    "method": "PATCH",
+    "path": "/v1/webhook-endpoints/{id}",
+    "description": "Enable only after configuring verification. Use enabled:false to pause, or revoke:true to permanently cancel queued deliveries; an in-flight HTTP request cannot be recalled.",
+    "input": "WebhookEndpointUpdate",
+    "auth": "management"
+  },
+  {
+    "name": "webhook_endpoints_rotate",
+    "method": "POST",
+    "path": "/v1/webhook-endpoints/{id}/rotate-key",
+    "description": "Install the new generation and retain the old receiver secret for five minutes. New claims use the new generation; identical rotation retries return the original protected result.",
+    "input": "WebhookOperationInput",
+    "auth": "management"
+  },
+  {
+    "name": "webhook_deliveries_list",
+    "method": "GET",
+    "path": "/v1/webhook-deliveries",
+    "description": "Inspect delivery status. Continue with after equal to the last returned UUID for a stable ordering of existing rows; this operational list is not a response snapshot.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "webhook_deliveries_get",
+    "method": "GET",
+    "path": "/v1/webhook-deliveries/{id}",
+    "description": "Read attempts, retry time and fixed failure code. Receiver bodies and survey answers are never exposed through delivery status.",
+    "input": "empty",
+    "auth": "management"
+  },
+  {
+    "name": "webhook_deliveries_replay",
+    "method": "POST",
+    "path": "/v1/webhook-deliveries/{id}/replay",
+    "description": "Requeue a completed or failed delivery before seven-day expiry, up to three times. The event ID remains unchanged; receivers deduplicate business processing by that ID.",
+    "input": "WebhookOperationInput",
+    "auth": "management"
+  }
+]