@genlobe/mcp-server 2.2.0 → 3.1.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 +193 -116
- package/dist/index.d.ts +1 -1
- package/dist/index.js +2203 -1474
- package/package.json +41 -41
package/README.md
CHANGED
|
@@ -1,116 +1,193 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
---
|
|
79
|
-
|
|
80
|
-
##
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
|
100
|
-
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
1
|
+
# Genlobe MCP Server
|
|
2
|
+
|
|
3
|
+
A Model Context Protocol (MCP) server that turns AI-enabled IDEs (Cursor, Claude Code, GitHub Copilot, Windsurf, etc.) into informed Genlobe API clients. The server hands the assistant up-to-date API docs, ready-to-use SDK templates, security guidance, and stack recommendations — so when a developer says *"build me a login screen"* or *"add a checkout flow"*, the assistant doesn't hallucinate endpoints.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@genlobe/mcp-server)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Two API surfaces — read this before installing
|
|
11
|
+
|
|
12
|
+
The Genlobe API exposes **two separate sets of endpoints**, and this MCP only documents one of them:
|
|
13
|
+
|
|
14
|
+
| Surface | Path prefix | Auth | Audience | Documented by this MCP? |
|
|
15
|
+
|---|---|---|---|---|
|
|
16
|
+
| **End-user API** | `/v1/auth/*`, `/v1/agents/*`, `/v1/organizations/*`, `/v1/external-agents/*`, … | `X-API-Key` + end-user JWT | What you build *for your customers* | ✅ Yes — this is what AI assistants need |
|
|
17
|
+
| **Tenant/Dashboard API** | `/v1/tenant-auth/*`, `/v1/dashboard/*` | Tenant member JWT | Internal tenant-admin dashboard | ❌ No — intentionally excluded |
|
|
18
|
+
|
|
19
|
+
**If your assistant ever suggests calling `/v1/dashboard/...` or `/v1/tenant-auth/...` from your end-user frontend, it's wrong.** The MCP server never returns those paths; that's by design.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
Pick the snippet that matches your IDE.
|
|
26
|
+
|
|
27
|
+
### Cursor / Claude Code / Windsurf (`.vscode/mcp.json` or equivalent)
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"servers": {
|
|
32
|
+
"genlobe": {
|
|
33
|
+
"command": "npx",
|
|
34
|
+
"args": ["-y", "@genlobe/mcp-server"],
|
|
35
|
+
"env": {
|
|
36
|
+
"SAAS_API_URL": "https://api-core.genlobe.ai",
|
|
37
|
+
"SAAS_API_KEY": "pk_live_or_sk_live_xxx"
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Claude Desktop (`claude_desktop_config.json`)
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"genlobe": {
|
|
50
|
+
"command": "npx",
|
|
51
|
+
"args": ["-y", "@genlobe/mcp-server"],
|
|
52
|
+
"env": {
|
|
53
|
+
"SAAS_API_URL": "https://api-core.genlobe.ai",
|
|
54
|
+
"SAAS_API_KEY": "pk_live_or_sk_live_xxx"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Restart the IDE and the `genlobe` server will show up in the MCP server list.
|
|
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`).
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Environment variables
|
|
68
|
+
|
|
69
|
+
| Variable | Required | What it's for |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| `SAAS_API_URL` | yes | Base URL of the Genlobe API. Use **`https://api-core.genlobe.ai`** in production. |
|
|
72
|
+
| `SAAS_API_KEY` | optional | Tenant API key. **Optional** for documentation tools, **required** for the live tools that actually call the API (`validate_credentials`, `list_end_users`, `list_oauth_providers`, `get_openapi_spec` against protected paths). Accepts both `pk_live_*` (public) and `sk_live_*` (secret). |
|
|
73
|
+
|
|
74
|
+
`API_URL` and `API_KEY` (without the `SAAS_` prefix) are accepted as aliases for backward compatibility.
|
|
75
|
+
|
|
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
|
+
---
|
|
79
|
+
|
|
80
|
+
## Tools
|
|
81
|
+
|
|
82
|
+
The server exposes 14 tools. They split into three categories:
|
|
83
|
+
|
|
84
|
+
### Documentation tools (offline, no API key needed)
|
|
85
|
+
|
|
86
|
+
| Tool | What it returns |
|
|
87
|
+
|---|---|
|
|
88
|
+
| `get_api_overview` | High-level architecture: the two API surfaces, auth model, key concepts, recommended call order. **Start here.** |
|
|
89
|
+
| `get_end_user_endpoints` | Detailed reference for every end-user endpoint, optionally filtered by category (`authentication`, `organizations`, `subscriptions`, `billing`, `usage`, `agents`, `users`, `plans`, `ai`, `entities`, `departments`, `files`, `external_agents`). |
|
|
90
|
+
| `get_request_headers` | The exact HTTP headers required for end-user requests, with examples (`X-API-Key`, `Authorization: Bearer …`, `Content-Type`, etc.). |
|
|
91
|
+
| `get_authentication_flow` | Step-by-step guide for register → login → refresh → logout, including token storage rules and refresh-on-401 patterns. |
|
|
92
|
+
| `get_common_patterns` | Frontend implementation patterns: pagination, error handling, optimistic updates, file upload, RAG queries, agent execution. |
|
|
93
|
+
| `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 (e.g. `"login"`, `"organization"`, `"checkout"`). |
|
|
95
|
+
| `get_endpoint_details` | Full request/response schema of a specific `(method, path)`. |
|
|
96
|
+
|
|
97
|
+
### Live tools (require `SAAS_API_KEY`)
|
|
98
|
+
|
|
99
|
+
| Tool | What it does |
|
|
100
|
+
|---|---|
|
|
101
|
+
| `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 the configured `SAAS_API_URL`. Reflects the deployed version of the API exactly. |
|
|
103
|
+
| `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, …) the tenant has enabled for end-user social login. Friendly empty-state when none are configured. |
|
|
105
|
+
|
|
106
|
+
### Security & architecture tools (key-aware, work without making calls)
|
|
107
|
+
|
|
108
|
+
| Tool | What it does |
|
|
109
|
+
|---|---|
|
|
110
|
+
| `get_security_guide` | Returns a key-type-specific safe-usage cheat sheet. For `pk_live_*`: the allowed endpoints and the "may be exposed in browser bundles" rule. For `sk_live_*`: leak vectors (frontend bundle, repo, client logs) and the server-only architecture pattern. |
|
|
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 *physically prevents the key from leaking*. Covers Next.js (App Router), Remix, SvelteKit, Nuxt, Astro for fullstack+secret; appropriate alternatives for the other shapes. |
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
## Recommended call order for AI assistants
|
|
116
|
+
|
|
117
|
+
This is also what the startup banner of the server prints:
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
1. validate_credentials → confirm SAAS_API_KEY works, learn its type
|
|
121
|
+
2. get_security_guide → know what you can and can't do with that key
|
|
122
|
+
3. recommend_stack → pick a framework that won't leak the key
|
|
123
|
+
4. get_api_overview → understand the API at a high level
|
|
124
|
+
5. get_authentication_flow → wire up register / login / refresh
|
|
125
|
+
6. get_end_user_endpoints → see what's available for the feature you're building
|
|
126
|
+
7. get_sdk_template → start writing real code
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
For *targeted* questions ("how do I list organizations?"), `search_endpoints` + `get_endpoint_details` is faster than scrolling through `get_end_user_endpoints`.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Local development
|
|
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:
|
|
144
|
+
|
|
145
|
+
```json
|
|
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
|
+
```
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Releasing a new version
|
|
163
|
+
|
|
164
|
+
The MCP version follows semver and is bumped independently of the backend API:
|
|
165
|
+
|
|
166
|
+
- **patch** — bug fix in a tool's behavior, doc correction
|
|
167
|
+
- **minor** — new tool, new optional field, new env var with a default
|
|
168
|
+
- **major** — tool removed/renamed, env var removed, breaking change in returned shape
|
|
169
|
+
|
|
170
|
+
Publish flow (works around the subtree quirk where `npm version` doesn't always commit cleanly):
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
cd mcp-server
|
|
174
|
+
# 1. Move CHANGELOG [Unreleased] section under the new version header.
|
|
175
|
+
# 2. Bump versions without letting npm touch git:
|
|
176
|
+
npm version <patch|minor|major> --no-git-tag-version
|
|
177
|
+
# 3. One commit + one tag, both intentional:
|
|
178
|
+
git add package.json package-lock.json CHANGELOG.md
|
|
179
|
+
git commit -m "chore(mcp): release vX.Y.Z"
|
|
180
|
+
git tag -a vX.Y.Z -m "@genlobe/mcp-server vX.Y.Z"
|
|
181
|
+
# 4. Publish (prepublishOnly runs `tsc` automatically):
|
|
182
|
+
npm publish --access public
|
|
183
|
+
# 5. Push commit + tag:
|
|
184
|
+
git push origin main && git push origin vX.Y.Z
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The CI workflow `.github/workflows/publish-mcp.yml` automates steps 4–5 when you push a `mcp-v*` tag (see [Automated publishing](#automated-publishing) below).
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## License
|
|
192
|
+
|
|
193
|
+
MIT — see [package.json](./package.json).
|
package/dist/index.d.ts
CHANGED