@genlobe/mcp-server 3.3.0 → 3.4.0
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.
- package/README.md +46 -68
- package/dist/index.js +12 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,34 +1,38 @@
|
|
|
1
1
|
# Genlobe MCP Server
|
|
2
2
|
|
|
3
|
-
A Model Context Protocol (MCP) server that
|
|
3
|
+
A Model Context Protocol (MCP) server that documents the [Genlobe](https://genlobe.ai) API so AI assistants in your IDE (Cursor, Claude Code, Windsurf, Claude Desktop, …) can build real clients against it — without hallucinating endpoints, shapes, or auth headers.
|
|
4
|
+
|
|
5
|
+
Paste it into your MCP config and ask your assistant *"build me a login screen"* or *"add a checkout flow"*. It will pull the right endpoints, headers, and code patterns straight from this server.
|
|
4
6
|
|
|
5
7
|
[](https://www.npmjs.com/package/@genlobe/mcp-server)
|
|
6
8
|
[](https://nodejs.org)
|
|
7
9
|
|
|
8
10
|
---
|
|
9
11
|
|
|
10
|
-
##
|
|
12
|
+
## What it documents
|
|
11
13
|
|
|
12
|
-
The Genlobe API
|
|
14
|
+
The Genlobe API has two surfaces. This server only exposes the one your end-user app should call:
|
|
13
15
|
|
|
14
|
-
| Surface | Path prefix | Auth |
|
|
15
|
-
|
|
16
|
-
| **End-user API** | `/v1/auth/*`, `/v1/agents/*`, `/v1/organizations/*`, `/v1/external-agents/*`, … | `X-API-Key` + end-user JWT |
|
|
17
|
-
|
|
|
16
|
+
| Surface | Path prefix | Auth | Documented here? |
|
|
17
|
+
|---|---|---|---|
|
|
18
|
+
| **End-user API** | `/v1/auth/*`, `/v1/agents/*`, `/v1/organizations/*`, `/v1/external-agents/*`, … | `X-API-Key` + end-user JWT | Yes |
|
|
19
|
+
| Tenant / Dashboard API | `/v1/tenant-auth/*`, `/v1/dashboard/*` | Tenant member JWT | No — by design |
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
If the assistant ever suggests calling `/v1/dashboard/...` or `/v1/tenant-auth/...` from your end-user frontend, it's wrong: those endpoints exist for tenant admins, not for the apps you build on Genlobe.
|
|
20
22
|
|
|
21
23
|
---
|
|
22
24
|
|
|
23
25
|
## Install
|
|
24
26
|
|
|
25
|
-
Pick the snippet that matches your IDE.
|
|
27
|
+
Pick the snippet that matches your IDE. Drop in your API key (get one from [genlobe.ai](https://genlobe.ai) → your Tenant Dashboard → API Keys), restart the IDE, and the `genlobe` server will appear in its MCP server list.
|
|
28
|
+
|
|
29
|
+
### Cursor / Claude Code / Windsurf
|
|
26
30
|
|
|
27
|
-
|
|
31
|
+
Edit `.cursor/mcp.json`, `~/.config/claude-code/mcp.json`, or your equivalent client config:
|
|
28
32
|
|
|
29
33
|
```json
|
|
30
34
|
{
|
|
31
|
-
"
|
|
35
|
+
"mcpServers": {
|
|
32
36
|
"genlobe": {
|
|
33
37
|
"command": "npx",
|
|
34
38
|
"args": ["-y", "@genlobe/mcp-server"],
|
|
@@ -41,7 +45,9 @@ Pick the snippet that matches your IDE.
|
|
|
41
45
|
}
|
|
42
46
|
```
|
|
43
47
|
|
|
44
|
-
### Claude Desktop
|
|
48
|
+
### Claude Desktop
|
|
49
|
+
|
|
50
|
+
Edit `claude_desktop_config.json`:
|
|
45
51
|
|
|
46
52
|
```json
|
|
47
53
|
{
|
|
@@ -58,63 +64,57 @@ Pick the snippet that matches your IDE.
|
|
|
58
64
|
}
|
|
59
65
|
```
|
|
60
66
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
> The package is published as `@genlobe/mcp-server` on the public npm registry; `npx -y` always pulls the latest version unless you pin one (`@genlobe/mcp-server@3.1.0`).
|
|
67
|
+
`npx -y` always pulls the latest version unless you pin one (`@genlobe/mcp-server@3.3.1`).
|
|
64
68
|
|
|
65
69
|
---
|
|
66
70
|
|
|
67
71
|
## Environment variables
|
|
68
72
|
|
|
69
|
-
| Variable | Required |
|
|
73
|
+
| Variable | Required | Value |
|
|
70
74
|
|---|---|---|
|
|
71
|
-
| `SAAS_API_URL` |
|
|
72
|
-
| `SAAS_API_KEY` | optional |
|
|
75
|
+
| `SAAS_API_URL` | no | Defaults to `https://api-core.genlobe.ai`. Override only if you point at a local or on-prem backend. |
|
|
76
|
+
| `SAAS_API_KEY` | optional | Your Genlobe API key. Accepts both `pk_live_*` (public) and `sk_live_*` (secret). Without it, only the offline documentation tools work — the four live tools (`validate_credentials`, `list_end_users`, `list_oauth_providers`, `get_openapi_spec`) need it. |
|
|
73
77
|
|
|
74
78
|
`API_URL` and `API_KEY` (without the `SAAS_` prefix) are accepted as aliases for backward compatibility.
|
|
75
79
|
|
|
76
|
-
> If `SAAS_API_URL` is not set, the server falls back to `http://localhost:8001` — useful only if you're running the Genlobe backend yourself in development (see [Local development](#local-development) below). For any normal install from npm, set `SAAS_API_URL` explicitly.
|
|
77
|
-
|
|
78
80
|
---
|
|
79
81
|
|
|
80
82
|
## Tools
|
|
81
83
|
|
|
82
|
-
|
|
84
|
+
14 tools, in three groups.
|
|
83
85
|
|
|
84
|
-
### Documentation
|
|
86
|
+
### Documentation (offline, no API key needed)
|
|
85
87
|
|
|
86
|
-
| Tool |
|
|
88
|
+
| Tool | Returns |
|
|
87
89
|
|---|---|
|
|
88
|
-
| `get_api_overview` | High-level architecture
|
|
89
|
-
| `get_end_user_endpoints` |
|
|
90
|
-
| `get_request_headers` | The exact HTTP headers required for end-user requests, with examples
|
|
91
|
-
| `get_authentication_flow` | Step-by-step
|
|
92
|
-
| `get_common_patterns` |
|
|
90
|
+
| `get_api_overview` | High-level architecture, auth model, key concepts, recommended call order. **Start here.** |
|
|
91
|
+
| `get_end_user_endpoints` | Reference for every end-user endpoint, filterable by category (`authentication`, `organizations`, `subscriptions`, `billing`, `usage`, `agents`, `users`, `plans`, `ai`, `entities`, `departments`, `files`, `external_agents`). |
|
|
92
|
+
| `get_request_headers` | The exact HTTP headers required for end-user requests, with examples. |
|
|
93
|
+
| `get_authentication_flow` | Step-by-step register → login → refresh → logout, including token storage and refresh-on-401 patterns. |
|
|
94
|
+
| `get_common_patterns` | Pagination, error handling, optimistic updates, file upload, RAG queries, agent execution. |
|
|
93
95
|
| `get_sdk_template` | A ready-to-paste TypeScript SDK module (`fetch`-based, typed) covering auth, agents, organizations, files, billing. |
|
|
94
|
-
| `search_endpoints` | Keyword search across path, summary, and description
|
|
95
|
-
| `get_endpoint_details` | Full request/response schema
|
|
96
|
+
| `search_endpoints` | Keyword search across path, summary, and description. |
|
|
97
|
+
| `get_endpoint_details` | Full request/response schema for a specific `(method, path)`. |
|
|
96
98
|
|
|
97
|
-
### Live
|
|
99
|
+
### Live (require `SAAS_API_KEY`)
|
|
98
100
|
|
|
99
|
-
| Tool |
|
|
101
|
+
| Tool | Does |
|
|
100
102
|
|---|---|
|
|
101
103
|
| `validate_credentials` | Probes the API with the configured key. Reports the detected key type (`pk_live_*` vs `sk_live_*`), masked prefix, success/failure of a sample call, and the resolved API URL. **Run this first in any session.** |
|
|
102
|
-
| `get_openapi_spec` | Fetches the live `/v1/openapi.json` from
|
|
104
|
+
| `get_openapi_spec` | Fetches the live `/v1/openapi.json` from `SAAS_API_URL`. Reflects the deployed API exactly. |
|
|
103
105
|
| `list_end_users` | `GET /v1/auth/users` — paginated list of end-users in the tenant. Requires `sk_live_*`. |
|
|
104
|
-
| `list_oauth_providers` | Lists the OAuth providers (Google, …)
|
|
106
|
+
| `list_oauth_providers` | Lists the OAuth providers (Google, …) enabled for end-user social login. |
|
|
105
107
|
|
|
106
|
-
### Security & architecture
|
|
108
|
+
### Security & architecture (key-aware, no network calls)
|
|
107
109
|
|
|
108
|
-
| Tool |
|
|
110
|
+
| Tool | Does |
|
|
109
111
|
|---|---|
|
|
110
|
-
| `get_security_guide` |
|
|
111
|
-
| `recommend_stack` | Given an `app_type` (`frontend_only`, `fullstack`, `backend_service`, `mobile_app`, `cli_tool`, `desktop_app`) plus the detected key type, returns a framework recommendation that
|
|
112
|
+
| `get_security_guide` | Key-type-specific safe-usage cheat sheet. For `pk_live_*`: allowed endpoints and the "may be exposed in browser bundles" rule. For `sk_live_*`: leak vectors and the server-only architecture pattern. |
|
|
113
|
+
| `recommend_stack` | Given an `app_type` (`frontend_only`, `fullstack`, `backend_service`, `mobile_app`, `cli_tool`, `desktop_app`) plus the detected key type, returns a framework recommendation that physically prevents the key from leaking (Next.js App Router, Remix, SvelteKit, Nuxt, Astro for fullstack + secret; appropriate alternatives elsewhere). |
|
|
112
114
|
|
|
113
115
|
---
|
|
114
116
|
|
|
115
|
-
## Recommended call order
|
|
116
|
-
|
|
117
|
-
This is also what the startup banner of the server prints:
|
|
117
|
+
## Recommended call order
|
|
118
118
|
|
|
119
119
|
```
|
|
120
120
|
1. validate_credentials → confirm SAAS_API_KEY works, learn its type
|
|
@@ -126,39 +126,17 @@ This is also what the startup banner of the server prints:
|
|
|
126
126
|
7. get_sdk_template → start writing real code
|
|
127
127
|
```
|
|
128
128
|
|
|
129
|
-
For
|
|
129
|
+
For targeted questions ("how do I list organizations?"), `search_endpoints` + `get_endpoint_details` is faster than scrolling through `get_end_user_endpoints`.
|
|
130
130
|
|
|
131
131
|
---
|
|
132
132
|
|
|
133
|
-
##
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
cd mcp-server
|
|
137
|
-
npm install
|
|
138
|
-
npm run build # tsc → dist/
|
|
139
|
-
npm run dev # tsx, hot-reload
|
|
140
|
-
npm pack # build a local .tgz to test in your IDE before publishing
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
To point your IDE at a local build instead of npm:
|
|
133
|
+
## Support
|
|
144
134
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
"servers": {
|
|
148
|
-
"genlobe-local": {
|
|
149
|
-
"command": "node",
|
|
150
|
-
"args": ["/absolute/path/to/mcp-server/dist/index.js"],
|
|
151
|
-
"env": {
|
|
152
|
-
"SAAS_API_URL": "http://localhost:8001",
|
|
153
|
-
"SAAS_API_KEY": "pk_live_xxx"
|
|
154
|
-
}
|
|
155
|
-
}
|
|
156
|
-
}
|
|
157
|
-
}
|
|
158
|
-
```
|
|
135
|
+
- Sign up and manage API keys: [genlobe.ai](https://genlobe.ai)
|
|
136
|
+
- Issues and feature requests: [github.com/KleioTechnology/saas-multi-agent-tenant-ui/issues](https://github.com/KleioTechnology/saas-multi-agent-tenant-ui/issues)
|
|
159
137
|
|
|
160
138
|
---
|
|
161
139
|
|
|
162
140
|
## License
|
|
163
141
|
|
|
164
|
-
MIT
|
|
142
|
+
MIT.
|
package/dist/index.js
CHANGED
|
@@ -29,7 +29,12 @@ import { createRequire } from "module";
|
|
|
29
29
|
const require = createRequire(import.meta.url);
|
|
30
30
|
const pkg = require("../package.json");
|
|
31
31
|
const SERVER_VERSION = pkg.version;
|
|
32
|
-
|
|
32
|
+
// Default to the public Genlobe API for npm-distributed installs (#268). A
|
|
33
|
+
// developer who installs this package and forgets to set SAAS_API_URL gets
|
|
34
|
+
// a working install pointed at production instead of `connection refused`.
|
|
35
|
+
// Override with `SAAS_API_URL=http://localhost:8001` when running against
|
|
36
|
+
// a local backend in development.
|
|
37
|
+
const API_URL = process.env.SAAS_API_URL || process.env.API_URL || "https://api-core.genlobe.ai";
|
|
33
38
|
const API_KEY = process.env.SAAS_API_KEY || process.env.API_KEY || "";
|
|
34
39
|
// Cache for API responses
|
|
35
40
|
const cache = new Map();
|
|
@@ -1190,20 +1195,24 @@ const END_USER_ENDPOINTS = {
|
|
|
1190
1195
|
{
|
|
1191
1196
|
id: "uuid",
|
|
1192
1197
|
tenant_id: "uuid",
|
|
1198
|
+
organization_id: "uuid - Org this agent belongs to. Tenant-catalog agents live in the Tenant's root Org; private agents live in customer Orgs (ADR-0006 v2 Hybrid Catalog)",
|
|
1199
|
+
is_public: "boolean - true when this agent is in the Tenant's catalog (visible to all customer Orgs of the Tenant)",
|
|
1200
|
+
forked_from_agent_id: "uuid | null - if this agent is a fork of a catalog agent, points to the source. Forks are independent (no template sync)",
|
|
1193
1201
|
name: "string",
|
|
1194
1202
|
description: "string | null",
|
|
1195
1203
|
system_prompt: "string",
|
|
1196
1204
|
response_type: "text | audio | video",
|
|
1197
1205
|
rag_provider: "NONE | GOOGLE_FILE_SEARCH",
|
|
1206
|
+
rag_role: "string | null - declarative tag matched against KnowledgeBase.role_tag in the caller's Org at runtime. Replaces the legacy single-store rag_config.store_id path (closes cross-org RAG leak G5)",
|
|
1198
1207
|
is_active: "boolean",
|
|
1199
|
-
rag_config: "object | null",
|
|
1208
|
+
rag_config: "object | null - DEPRECATED. New agents should use rag_role + a per-Org KnowledgeBase",
|
|
1200
1209
|
mcp_servers: "array of MCP server configs",
|
|
1201
1210
|
created_by: "uuid",
|
|
1202
1211
|
created_at: "ISO datetime",
|
|
1203
1212
|
updated_at: "ISO datetime"
|
|
1204
1213
|
}
|
|
1205
1214
|
],
|
|
1206
|
-
note: "Returns only active agents
|
|
1215
|
+
note: "Returns only active agents visible to the calling Organization: the Org's own private agents UNION public agents in the Tenant's catalog (root Org). End-user JWT context determines the Org via current_user.default_organization_id."
|
|
1207
1216
|
},
|
|
1208
1217
|
{
|
|
1209
1218
|
method: "GET",
|
package/package.json
CHANGED