@bixbd/utils-mcp 0.0.0-stage → 0.1.0-beta.2

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@bixbd/utils-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "description": "Connect utility portals to AI agents through MCP",
+  "type": "module",
+  "bin": {
+    "utils-mcp": "src/cli.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "echo \"server: runs from source with Bun\"",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "start": "bun src/cli.ts"
+  },
+  "dependencies": {
+    "@bixbd/utils-mcp-core": "0.1.0-beta.2",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@bixbd/utils-mcp-connector-example": "0.0.0",
+    "@bixbd/utils-mcp-connector-desco": "0.1.0-beta.2"
+  },
+  "peerDependencies": {
+    "@bixbd/utils-mcp-connector-example": "*",
+    "@bixbd/utils-mcp-connector-desco": "*"
+  },
+  "peerDependenciesMeta": {
+    "@bixbd/utils-mcp-connector-example": {
+      "optional": true
+    },
+    "@bixbd/utils-mcp-connector-desco": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bixbd/utils-mcp.git",
+    "directory": "packages/server"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+import { loadConfig } from "./config";
+import { loadConnectors } from "./load";
+import { startServer } from "./server";
+
+// stdout is the MCP protocol channel. Log to stderr only.
+const log = (message: string) => process.stderr.write(`utils-mcp: ${message}\n`);
+
+try {
+  const config = await loadConfig();
+  if (config.enabled.length === 0) {
+    log('no connectors enabled. Create ~/.utils-mcp/config.json with {"enabled": ["desco"]}.');
+  }
+  const connectors = await loadConnectors(config.enabled);
+  await startServer(connectors, config.enabled);
+} catch (error) {
+  log(error instanceof Error ? error.message : "failed to start");
+  process.exit(1);
+}

package/src/config.ts

@@ -0,0 +1,26 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type Config = { enabled: string[] };
+
+export const DEFAULT_CONFIG: Config = { enabled: [] };
+
+export function configPath(env: Record<string, string | undefined> = process.env): string {
+  return env.UTILS_MCP_CONFIG ?? join(homedir(), ".utils-mcp", "config.json");
+}
+
+export function parseConfig(raw: string): Config {
+  const data = JSON.parse(raw) as { enabled?: unknown };
+  if (!Array.isArray(data.enabled) || !data.enabled.every((x) => typeof x === "string")) {
+    throw new Error('Config must look like {"enabled": ["connector-id"]}');
+  }
+  return { enabled: data.enabled as string[] };
+}
+
+export async function loadConfig(path = configPath()): Promise<Config> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    return DEFAULT_CONFIG;
+  }
+  return parseConfig(await file.text());
+}

package/src/context.ts

@@ -0,0 +1,33 @@
+import { envSecrets, type JsonSchema, type RuntimeContext } from "@bixbd/utils-mcp-core";
+
+/** Every tool accepts an optional `account` label. The server adds it, so connectors don't have to. */
+export function withAccountInput(schema: JsonSchema): JsonSchema {
+  return {
+    ...schema,
+    properties: {
+      ...schema.properties,
+      account: {
+        type: "string",
+        description: 'Account label to use. Defaults to "default".',
+      },
+    },
+  };
+}
+
+export function splitAccount(args: Record<string, unknown>): {
+  account: string;
+  input: Record<string, unknown>;
+} {
+  const { account, ...input } = args;
+  return {
+    account: typeof account === "string" && account !== "" ? account : "default",
+    input,
+  };
+}
+
+export function buildContext(
+  account: string,
+  env: Record<string, string | undefined> = process.env,
+): RuntimeContext {
+  return { account, fetch, secrets: envSecrets(account, env) };
+}

package/src/load.ts

@@ -0,0 +1,54 @@
+import type { Connector } from "@bixbd/utils-mcp-core";
+
+export type Importer = (specifier: string) => Promise<unknown>;
+
+const ID = /^[a-z][a-z0-9-]*$/;
+
+export const packageFor = (id: string) => `@bixbd/utils-mcp-connector-${id}`;
+
+function isConnector(value: unknown): value is Connector {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate.id === "string" &&
+    typeof candidate.baseUrl === "string" &&
+    Array.isArray(candidate.tools) &&
+    typeof candidate.auth === "object" &&
+    candidate.auth !== null
+  );
+}
+
+/**
+ * Loads each enabled connector from its own package, so the server never
+ * depends on connectors directly. Each package must default-export a connector.
+ */
+export async function loadConnectors(
+  ids: string[],
+  importer: Importer = (specifier) => import(specifier),
+): Promise<Connector[]> {
+  return Promise.all(
+    ids.map(async (id) => {
+      // Restrict what can be imported: only our own connector packages.
+      if (!ID.test(id)) {
+        throw new Error(`Invalid connector id "${id}". Use lowercase kebab-case.`);
+      }
+      const specifier = packageFor(id);
+      let mod: unknown;
+      try {
+        mod = await importer(specifier);
+      } catch {
+        throw new Error(`Connector "${id}" is enabled but ${specifier} could not be loaded. Install it with: bun add ${specifier}`);
+      }
+      const connector = (mod as { default?: unknown }).default;
+      if (!isConnector(connector)) {
+        throw new Error(`${specifier} must default-export a connector made with defineConnector.`);
+      }
+      if (connector.id !== id) {
+        throw new Error(`${specifier} exports connector "${connector.id}", expected "${id}".`);
+      }
+      return connector;
+    }),
+  );
+}

package/src/server.ts

@@ -0,0 +1,35 @@
+import { createRegistry, type Connector } from "@bixbd/utils-mcp-core";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { buildContext, splitAccount, withAccountInput } from "./context";
+
+export async function startServer(connectors: Connector[], enabled: string[]): Promise<void> {
+  const registry = createRegistry(connectors, enabled);
+  const server = new Server({ name: "utils-mcp", version: "0.0.0" }, { capabilities: { tools: {} } });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: registry.listTools().map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: withAccountInput(t.inputSchema),
+      outputSchema: t.outputSchema,
+      annotations: t.annotations,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const args = (request.params.arguments ?? {}) as Record<string, unknown>;
+    const { account, input } = splitAccount(args);
+    const result = await registry.callTool(request.params.name, input, buildContext(account));
+    if (result.ok) {
+      return {
+        content: [{ type: "text", text: JSON.stringify(result.data) }],
+        structuredContent: result.data as Record<string, unknown>,
+      };
+    }
+    return { isError: true, content: [{ type: "text", text: JSON.stringify(result.error) }] };
+  });
+
+  await server.connect(new StdioServerTransport());
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.