@genlobe/mcp-server 3.1.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.
Files changed (2) hide show
  1. package/README.md +151 -44
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,86 +1,193 @@
1
- # 🔌 MCP Server for Multi-tenant SaaS API
1
+ # Genlobe MCP Server
2
2
 
3
- This MCP Server provides AI-enabled IDEs (GitHub Copilot, Cursor, Claude, etc.) with comprehensive API documentation to help build frontend applications.
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
4
 
5
- ## ⚠️ Important: Two Types of Endpoints
5
+ [![npm version](https://img.shields.io/npm/v/@genlobe/mcp-server.svg)](https://www.npmjs.com/package/@genlobe/mcp-server)
6
+ [![Node](https://img.shields.io/node/v/@genlobe/mcp-server.svg)](https://nodejs.org)
6
7
 
7
- This API has **TWO types of endpoints**:
8
+ ---
9
+
10
+ ## Two API surfaces — read this before installing
8
11
 
9
- 1. **Tenant/Dashboard endpoints** (`/v1/tenant-auth/*`, `/v1/dashboard/*`)
10
- - For tenant admins managing their SaaS account
11
- - Uses JWT from tenant login
12
- - **NOT for end-user frontends**
12
+ The Genlobe API exposes **two separate sets of endpoints**, and this MCP only documents one of them:
13
13
 
14
- 2. **End-user endpoints** (`/v1/auth/*`, `/v1/organizations/*`, etc.)
15
- - For building frontend applications
16
- - Uses API Key (`X-API-Key`) + User JWT
17
- - **USE THESE for end-user frontends**
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
18
 
19
- ## 🚀 Installation
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
+ ---
20
22
 
21
- Add this to your project's `.vscode/mcp.json`:
23
+ ## Install
24
+
25
+ Pick the snippet that matches your IDE.
26
+
27
+ ### Cursor / Claude Code / Windsurf (`.vscode/mcp.json` or equivalent)
22
28
 
23
29
  ```json
24
30
  {
25
31
  "servers": {
26
- "multiagent": {
32
+ "genlobe": {
27
33
  "command": "npx",
28
- "args": ["-y", "https://api.your-domain.com/static/mcp-server.tgz"],
34
+ "args": ["-y", "@genlobe/mcp-server"],
29
35
  "env": {
30
- "SAAS_API_URL": "https://api.your-domain.com"
36
+ "SAAS_API_URL": "https://api-core.genlobe.ai",
37
+ "SAAS_API_KEY": "pk_live_or_sk_live_xxx"
31
38
  }
32
39
  }
33
40
  }
34
41
  }
35
42
  ```
36
43
 
37
- Restart VS Code and you're ready!
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`).
38
64
 
39
65
  ---
40
66
 
41
- ## 🛠️ Available Tools
67
+ ## Environment variables
42
68
 
43
- | Tool | Description |
44
- |------|-------------|
45
- | `get_api_overview` | High-level API architecture overview |
46
- | `get_end_user_endpoints` | Detailed documentation for end-user endpoints |
47
- | `get_request_headers` | Required HTTP headers for API requests |
48
- | `get_sdk_template` | Complete TypeScript SDK template |
49
- | `get_authentication_flow` | Step-by-step auth implementation guide |
50
- | `get_common_patterns` | Best practices for frontend development |
51
- | `search_endpoints` | Search endpoints by keyword |
52
- | `get_endpoint_details` | Get details of a specific endpoint |
53
- | `get_openapi_spec` | Full OpenAPI specification from live API |
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.
54
77
 
55
78
  ---
56
79
 
57
- ## 📋 Quick Start for AI Assistants
80
+ ## Tools
81
+
82
+ The server exposes 14 tools. They split into three categories:
58
83
 
59
- When building a frontend for end-users:
84
+ ### Documentation tools (offline, no API key needed)
60
85
 
61
- 1. **Call `get_api_overview`** first to understand the architecture
62
- 2. **Call `get_authentication_flow`** to implement login/register
63
- 3. **Call `get_end_user_endpoints`** to see all available endpoints
64
- 4. **Call `get_sdk_template`** to get a ready-to-use API client
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. |
65
112
 
66
113
  ---
67
114
 
68
- ## 📦 Local Development
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
69
134
 
70
135
  ```bash
71
136
  cd mcp-server
72
137
  npm install
73
- npm run build
74
- npm pack # Creates .tgz package
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
+ }
75
158
  ```
76
159
 
77
160
  ---
78
161
 
79
- ## 🔧 Environment Variables
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):
80
171
 
81
- | Variable | Description | Required |
82
- |----------|-------------|----------|
83
- | `SAAS_API_URL` | API base URL | Yes |
84
- | `SAAS_API_KEY` | API Key for accessing protected docs | No |
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
+ ---
85
190
 
191
+ ## License
86
192
 
193
+ MIT — see [package.json](./package.json).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@genlobe/mcp-server",
3
- "version": "3.1.0",
3
+ "version": "3.1.1",
4
4
  "description": "MCP Server for GenLobe SaaS API - Provides AI assistants with comprehensive API documentation for building frontend applications",
5
5
  "main": "dist/index.js",
6
6
  "bin": {