@genlobe/mcp-server 3.3.0 → 3.3.1
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/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` | yes |
|
|
72
|
-
| `SAAS_API_KEY` | optional |
|
|
75
|
+
| `SAAS_API_URL` | yes | `https://api-core.genlobe.ai` |
|
|
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) (this single tracker covers the whole Genlobe platform, including this MCP server)
|
|
159
137
|
|
|
160
138
|
---
|
|
161
139
|
|
|
162
140
|
## License
|
|
163
141
|
|
|
164
|
-
MIT
|
|
142
|
+
MIT.
|
package/package.json
CHANGED