@onegovpolicy/claude-desktop-mcp 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# OneGov Claude Desktop MCP Connector
+
+This package is the small local MCP process used by Claude Desktop. It does not connect to the
+OneGov database or require a source checkout. It fetches the MCP tool catalog from the OneGov
+website and proxies tool calls to `/api/mcp/invoke` with an account-scoped API key.
+
+Node.js 20 or newer is required.
+
+Use the config generated in OneGov Settings -> Integrations -> Claude Desktop MCP.
+
+```json
+{
+  "mcpServers": {
+    "onegov": {
+      "command": "npx",
+      "args": ["-y", "@onegovpolicy/claude-desktop-mcp"],
+      "env": {
+        "ONEGOV_API_BASE_URL": "https://your-onegov-website.example",
+        "ONEGOV_MCP_API_KEY": "og_mcp_replace_with_generated_key"
+      }
+    }
+  }
+}
+```
+
+The key is stored in plaintext in Claude Desktop's config file until it is removed. Revoke unused
+keys from the OneGov integrations page.

package/bin/onegov-claude-desktop-mcp.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const VERSION = '0.1.0';
+
+const jsonResult = (value) => ({
+  content: [
+    {
+      type: 'text',
+      text: JSON.stringify(value, null, 2),
+    },
+  ],
+});
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+function getString(value) {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function getApiBaseUrl() {
+  const value = process.env.ONEGOV_API_BASE_URL?.trim();
+  if (!value) {
+    throw new Error('Set ONEGOV_API_BASE_URL to your OneGov website URL.');
+  }
+  return value.replace(/\/$/, '');
+}
+
+function getApiKey() {
+  const value = process.env.ONEGOV_MCP_API_KEY?.trim();
+  if (!value) {
+    throw new Error('Set ONEGOV_MCP_API_KEY to an active account-scoped MCP API key.');
+  }
+  return value;
+}
+
+function getSchemaType(schema) {
+  const type = schema.type;
+  if (typeof type === 'string') {
+    return type;
+  }
+  if (Array.isArray(type)) {
+    return type.find((item) => typeof item === 'string' && item !== 'null');
+  }
+  return undefined;
+}
+
+function getRequiredNames(schema) {
+  const required = schema.required;
+  const names = new Set();
+  if (!Array.isArray(required)) {
+    return names;
+  }
+  for (const item of required) {
+    if (typeof item === 'string') {
+      names.add(item);
+    }
+  }
+  return names;
+}
+
+function getEnumValues(schema) {
+  const values = schema.enum;
+  if (!Array.isArray(values)) {
+    return [];
+  }
+  return values.filter((value) => typeof value === 'string');
+}
+
+function withDescription(schema, source) {
+  const description = getString(source.description);
+  return description ? schema.describe(description) : schema;
+}
+
+function jsonSchemaPropertyToZod(schema) {
+  if (!isRecord(schema)) {
+    return z.unknown();
+  }
+
+  const enumValues = getEnumValues(schema);
+  if (enumValues.length > 0) {
+    return withDescription(
+      z.string().refine((value) => enumValues.includes(value), {
+        message: `Expected one of: ${enumValues.join(', ')}`,
+      }),
+      schema,
+    );
+  }
+
+  const type = getSchemaType(schema);
+  if (type === 'string') {
+    return withDescription(z.string(), schema);
+  }
+  if (type === 'number' || type === 'integer') {
+    const numberSchema = type === 'integer' ? z.number().int() : z.number();
+    return withDescription(numberSchema, schema);
+  }
+  if (type === 'boolean') {
+    return withDescription(z.boolean(), schema);
+  }
+  if (type === 'array') {
+    const items = isRecord(schema.items) ? jsonSchemaPropertyToZod(schema.items) : z.unknown();
+    return withDescription(z.array(items), schema);
+  }
+  if (type === 'object') {
+    return withDescription(buildZodObjectFromJsonSchema(schema), schema);
+  }
+  return withDescription(z.unknown(), schema);
+}
+
+function buildZodObjectFromJsonSchema(parameters) {
+  if (!isRecord(parameters)) {
+    return z.object({});
+  }
+
+  const properties = isRecord(parameters.properties) ? parameters.properties : {};
+  const required = getRequiredNames(parameters);
+  const shape = {};
+  for (const [name, property] of Object.entries(properties)) {
+    const propertySchema = jsonSchemaPropertyToZod(property);
+    shape[name] = required.has(name) ? propertySchema : propertySchema.optional();
+  }
+
+  return parameters.additionalProperties === true ? z.object(shape).passthrough() : z.object(shape);
+}
+
+function isMcpToolDefinition(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  if (value.type !== 'function' || !isRecord(value.function)) {
+    return false;
+  }
+  return (
+    typeof value.function.name === 'string' &&
+    typeof value.function.description === 'string' &&
+    'parameters' in value.function
+  );
+}
+
+function parseToolDefinitionsPayload(payload) {
+  if (!isRecord(payload) || !Array.isArray(payload.tools)) {
+    throw new Error('OneGov returned an invalid MCP tool catalog.');
+  }
+
+  const tools = [];
+  for (const item of payload.tools) {
+    if (isMcpToolDefinition(item)) {
+      tools.push(item);
+    }
+  }
+  return tools;
+}
+
+async function readJsonResponse(response) {
+  const responseText = await response.text();
+  if (responseText.length === 0) {
+    return null;
+  }
+  try {
+    return JSON.parse(responseText);
+  } catch {
+    return responseText;
+  }
+}
+
+async function fetchMcpToolDefinitions() {
+  const response = await fetch(`${getApiBaseUrl()}/api/mcp/tools`, {
+    headers: {
+      Authorization: `Bearer ${getApiKey()}`,
+    },
+  });
+  const payload = await readJsonResponse(response);
+  if (!response.ok) {
+    const message =
+      isRecord(payload) && typeof payload.message === 'string'
+        ? payload.message
+        : `OneGov returned HTTP ${response.status} while loading MCP tools`;
+    throw new Error(message);
+  }
+  return parseToolDefinitionsPayload(payload);
+}
+
+async function postToolInvocation(toolName, args) {
+  const response = await fetch(`${getApiBaseUrl()}/api/mcp/invoke`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${getApiKey()}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ toolName, args }),
+  });
+
+  const payload = await readJsonResponse(response);
+  if (!response.ok) {
+    const message =
+      isRecord(payload) && typeof payload.message === 'string'
+        ? payload.message
+        : `OneGov returned HTTP ${response.status}`;
+    throw new Error(message);
+  }
+
+  return isRecord(payload) && 'result' in payload ? payload.result : payload;
+}
+
+async function createServer() {
+  const toolDefinitions = await fetchMcpToolDefinitions();
+  const server = new McpServer({
+    name: 'onegov',
+    version: VERSION,
+  });
+
+  server.registerTool(
+    'onegov_health',
+    {
+      title: 'OneGov MCP Health',
+      description: 'Checks Claude Desktop MCP configuration and the OneGov website connection.',
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    },
+    async () =>
+      jsonResult({
+        status: 'ok',
+        apiBaseUrl: getApiBaseUrl(),
+        apiKeyConfigured: Boolean(process.env.ONEGOV_MCP_API_KEY?.trim()),
+        exposedToolCount: toolDefinitions.length,
+      }),
+  );
+
+  for (const tool of toolDefinitions) {
+    const toolName = tool.function.name;
+    const inputSchema = buildZodObjectFromJsonSchema(tool.function.parameters);
+    server.registerTool(
+      toolName,
+      {
+        title: toolName,
+        description: tool.function.description,
+        inputSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+      },
+      async (args) => {
+        const toolArgs = isRecord(args) ? args : {};
+        const result = await postToolInvocation(toolName, toolArgs);
+        return jsonResult(result);
+      },
+    );
+  }
+
+  return server;
+}
+
+async function main() {
+  const server = await createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+  process.stderr.write(`OneGov MCP connector failed to start: ${message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@onegovpolicy/claude-desktop-mcp",
+  "version": "0.1.0",
+  "description": "Claude Desktop MCP connector for OneGov",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "onegov-claude-desktop-mcp": "bin/onegov-claude-desktop-mcp.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19.0 <21"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.2"
+  }
+}