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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BIXBD
+
+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

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @bixbd/utils-mcp
 
-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.
+Connect utility portals to AI agents through the [Model Context Protocol](https://modelcontextprotocol.io). It runs on your own computer over stdio, so your credentials never leave your machine.
+
+> **Beta.** Expect changes. Published under the `next` tag.
+
+## What it does
+
+You enable the connectors you want. Each connector adds a few task-shaped tools (like `desco_get_balance`) to your AI app. Only enabled connectors are loaded, so the AI's tool list stays small.
+
+| Connector | Tools | Credentials |
+| --- | --- | --- |
+| `desco` ([package](https://www.npmjs.com/package/@bixbd/utils-mcp-connector-desco)) | `desco_list_accounts`, `desco_get_balance`, `desco_get_realtime_status` | `DESCO_USERNAME`, `DESCO_PASSWORD` |
+| `example` (repo only) | `example_get_status` | none |
+
+## Requirements
+
+[Bun](https://bun.sh) 1.1 or newer. The server runs TypeScript directly with Bun.
+
+## Install
+
+Install the server and the connectors you need into one folder. Connectors are separate packages, and the server loads them from the folder it is installed in.
+
+```bash
+mkdir -p ~/.utils-mcp && cd ~/.utils-mcp
+bun add @bixbd/utils-mcp@next @bixbd/utils-mcp-connector-desco@next
+```
+
+## Choose connectors
+
+Create `~/.utils-mcp/config.json`. Nothing is enabled by default.
+
+```json
+{ "enabled": ["desco"] }
+```
+
+Each name `<id>` loads the package `@bixbd/utils-mcp-connector-<id>`, so it must be installed in the same folder.
+
+## Add it to your AI app
+
+Use the full path, because most apps do not expand `~`.
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "utils": {
+      "command": "/Users/you/.utils-mcp/node_modules/.bin/utils-mcp",
+      "env": { "DESCO_USERNAME": "your-username", "DESCO_PASSWORD": "your-password" }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add utils -e DESCO_USERNAME=your-username -e DESCO_PASSWORD=your-password -- ~/.utils-mcp/node_modules/.bin/utils-mcp
+```
+
+Restart the app, then ask something like "What is my DESCO balance?"
+
+## Multiple accounts
+
+Add a label after two underscores and pass it as `account` in the tool call:
+
+```
+DESCO_USERNAME__OFFICE=...
+DESCO_PASSWORD__OFFICE=...
+```
+
+Then ask "check the office DESCO account", and the AI calls the tool with `account: "office"`. Without a label, the default account is used.
+
+## Troubleshooting
+
+| Message | Fix |
+| --- | --- |
+| `no connectors enabled` | Create `~/.utils-mcp/config.json` with `{"enabled": ["desco"]}`. |
+| Cannot find the connector package | Run `bun add @bixbd/utils-mcp-connector-<id>@next` inside `~/.utils-mcp`. |
+| A tool says credentials are missing | Add the environment variables to your app's MCP config (the `env` block). |
+| The portal changed | The tool returns `UPSTREAM_CHANGED`. Open an issue with the tool name. |
+
+Set the config path with `UTILS_MCP_CONFIG=/path/to/config.json` if you keep it elsewhere. Logs go to stderr, never stdout.
+
+## Security
+
+- Credentials come from environment variables and are sent only to the portal over HTTPS.
+- Sessions are kept in memory only. Nothing is written to disk.
+- Account numbers are masked in tool output.
+- Use only accounts you own or have permission to access. Connectors are unofficial and not affiliated with the portals.
+
+## Links
+
+[Source and issues](https://github.com/bixbd/utils-mcp) · [Write a connector](https://github.com/bixbd/utils-mcp/blob/main/CONTRIBUTING.md) · MIT License

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@bixbd/utils-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.3",
+  "description": "Connect utility portals to AI agents through MCP. Local stdio server for Bun; credentials stay on your machine.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "claude",
+    "bun",
+    "utilities",
+    "portals",
+    "stdio"
+  ],
+  "license": "MIT",
+  "author": "BIXBD (https://github.com/bixbd)",
+  "homepage": "https://github.com/bixbd/utils-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/bixbd/utils-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bixbd/utils-mcp.git",
+    "directory": "packages/server"
+  },
+  "type": "module",
+  "bin": {
+    "utils-mcp": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "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.3",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@bixbd/utils-mcp-connector-example": "0.0.0",
+    "@bixbd/utils-mcp-connector-desco": "0.1.0-beta.3"
+  },
+  "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
+    }
+  }
+}

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());
+}