@bixbd/utils-mcp 0.1.0-beta.2 → 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

@@ -0,0 +1,95 @@
+# @bixbd/utils-mcp
+
+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,14 +1,43 @@
 {
   "name": "@bixbd/utils-mcp",
-  "version": "0.1.0-beta.2",
-  "description": "Connect utility portals to AI agents through MCP",
+  "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"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "echo \"server: runs from source with Bun\"",
     "typecheck": "tsc --noEmit",
@@ -16,12 +45,12 @@
     "start": "bun src/cli.ts"
   },
   "dependencies": {
-    "@bixbd/utils-mcp-core": "0.1.0-beta.2",
+    "@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.2"
+    "@bixbd/utils-mcp-connector-desco": "0.1.0-beta.3"
   },
   "peerDependencies": {
     "@bixbd/utils-mcp-connector-example": "*",
@@ -34,16 +63,5 @@
     "@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"
   }
 }