@bixbd/utils-mcp 0.1.0-beta.3 → 0.1.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +26 -24
  2. package/dist/cli.js +20293 -0
  3. package/package.json +12 -25
  4. package/src/cli.ts +0 -19
  5. package/src/config.ts +0 -26
  6. package/src/context.ts +0 -33
  7. package/src/load.ts +0 -54
  8. package/src/server.ts +0 -35
package/README.md CHANGED
@@ -15,51 +15,53 @@ You enable the connectors you want. Each connector adds a few task-shaped tools
15
15
 
16
16
  ## Requirements
17
17
 
18
- [Bun](https://bun.sh) 1.1 or newer. The server runs TypeScript directly with Bun.
18
+ [Node.js](https://nodejs.org) 18 or newer. The package is a single file with no dependencies, and the `desco` connector is built in.
19
19
 
20
20
  ## Install
21
21
 
22
- 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.
22
+ **Claude Desktop, no terminal:** download `utils-mcp.mcpb` from the [latest release](https://github.com/bixbd/utils-mcp/releases), double-click it and enter your login. Claude Desktop keeps the password in the OS keychain. (Build it yourself with `bun run pack:mcpb`.)
23
23
 
24
- ```bash
25
- mkdir -p ~/.utils-mcp && cd ~/.utils-mcp
26
- bun add @bixbd/utils-mcp@next @bixbd/utils-mcp-connector-desco@next
27
- ```
28
-
29
- ## Choose connectors
30
-
31
- Create `~/.utils-mcp/config.json`. Nothing is enabled by default.
24
+ **Any app:** run the setup. It asks for your portal login, finds your AI apps and configures them:
32
25
 
33
- ```json
34
- { "enabled": ["desco"] }
26
+ ```bash
27
+ npx -y @bixbd/utils-mcp@next setup
35
28
  ```
36
29
 
37
- Each name `<id>` loads the package `@bixbd/utils-mcp-connector-<id>`, so it must be installed in the same folder.
38
-
39
- ## Add it to your AI app
30
+ It supports Claude Desktop, Claude Code, Cursor, Windsurf, VS Code and Gemini CLI. For anything else it prints a snippet to paste. Restart your AI app afterwards and ask something like "What is my DESCO balance?"
40
31
 
41
- Use the full path, because most apps do not expand `~`.
32
+ ## Add it by hand
42
33
 
43
- **Claude Desktop** (`claude_desktop_config.json`):
34
+ Every MCP app takes the same three things: a command, arguments and environment variables.
44
35
 
45
36
  ```json
46
37
  {
47
38
  "mcpServers": {
48
39
  "utils": {
49
- "command": "/Users/you/.utils-mcp/node_modules/.bin/utils-mcp",
40
+ "command": "npx",
41
+ "args": ["-y", "@bixbd/utils-mcp@next"],
50
42
  "env": { "DESCO_USERNAME": "your-username", "DESCO_PASSWORD": "your-password" }
51
43
  }
52
44
  }
53
45
  }
54
46
  ```
55
47
 
56
- **Claude Code:**
48
+ VS Code uses the key `servers` instead of `mcpServers`. For Claude Code:
57
49
 
58
50
  ```bash
59
- claude mcp add utils -e DESCO_USERNAME=your-username -e DESCO_PASSWORD=your-password -- ~/.utils-mcp/node_modules/.bin/utils-mcp
51
+ claude mcp add utils -e DESCO_USERNAME=your-username -e DESCO_PASSWORD=your-password -- npx -y @bixbd/utils-mcp@next
52
+ ```
53
+
54
+ If an app cannot find `npx` (some desktop apps do not see your shell PATH), use the full path from `which npx` as the command.
55
+
56
+ ## Choose connectors
57
+
58
+ By default every built-in connector is on, and only the ones with credentials will work. To limit them, set `UTILS_MCP_ENABLED=desco` (comma separated) in the same `env` block. Alternatively, create `~/.utils-mcp/config.json`:
59
+
60
+ ```json
61
+ { "enabled": ["desco"] }
60
62
  ```
61
63
 
62
- Restart the app, then ask something like "What is my DESCO balance?"
64
+ Connectors that are not built in are separate packages (`@bixbd/utils-mcp-connector-<id>`) that you install next to the server.
63
65
 
64
66
  ## Multiple accounts
65
67
 
@@ -76,8 +78,8 @@ Then ask "check the office DESCO account", and the AI calls the tool with `accou
76
78
 
77
79
  | Message | Fix |
78
80
  | --- | --- |
79
- | `no connectors enabled` | Create `~/.utils-mcp/config.json` with `{"enabled": ["desco"]}`. |
80
- | Cannot find the connector package | Run `bun add @bixbd/utils-mcp-connector-<id>@next` inside `~/.utils-mcp`. |
81
+ | Cannot find the connector package | Only built-in connectors work out of the box. Install others with `npm install @bixbd/utils-mcp-connector-<id>@next` in the folder the server runs from. |
82
+ | The app says the server failed to start | Install Node.js 18+, or put the full path to `npx` in the config. |
81
83
  | A tool says credentials are missing | Add the environment variables to your app's MCP config (the `env` block). |
82
84
  | The portal changed | The tool returns `UPSTREAM_CHANGED`. Open an issue with the tool name. |
83
85
 
@@ -92,4 +94,4 @@ Set the config path with `UTILS_MCP_CONFIG=/path/to/config.json` if you keep it
92
94
 
93
95
  ## Links
94
96
 
95
- [Source and issues](https://github.com/bixbd/utils-mcp) · [Write a connector](https://github.com/bixbd/utils-mcp/blob/main/CONTRIBUTING.md) · MIT License
97
+ [Source and issues](https://github.com/bixbd/utils-mcp) · [Write a connector](https://github.com/bixbd/utils-mcp/blob/main/docs/ADDING_A_CONNECTOR.md) · MIT License