@norbix.ai/mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,284 @@
-# Temporary Holding Version
+# Norbix MCP Server (`@norbix.ai/mcp`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Work with your Norbix backend from any AI tool that speaks MCP — Claude
+Desktop, Claude Code, Cursor, VS Code, Windsurf, and others. Create projects,
+manage integrations, query databases, manage users, read logs — everything
+your API key is allowed to do.
+
+Built on the official [`@norbix.ai/ts`](../norbix-js) SDK. Covers **every**
+Norbix Hub and API endpoint (640+) through a small tool set.
+
+## What you need
+
+1. **A Norbix API key (service user).**
+   In the Norbix dashboard, open your project → *Membership* → *Service
+   users*. Create a service user, give it a role (for example *Project
+   Administrator* for full project access), and issue an API key.
+   The key's permissions decide what the MCP server can do.
+2. **Your Norbix Hub endpoint** (for example `https://hub.norbix.ai`, or
+   your own host on a self-hosted install). The server calls `/echo` on
+   startup to discover the rest (API URL, versions, regions).
+
+## Configuration (environment variables)
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `NORBIX_API_KEY` | yes | Service-user API key (sent as `Authorization: Bearer`). |
+| `NORBIX_HUB_URL` | yes | Norbix Hub endpoint. |
+| `NORBIX_PROJECT_ID` | no | Default project to work in. You can also switch at any time with the `norbix_set_project` tool. |
+| `NORBIX_API_URL` | no | API endpoint. Discovered from `/echo` when not set. |
+| `NORBIX_ENV` | no | Project environment (e.g. `DEV`). Default is `PROD`. |
+| `NORBIX_REGION` | no | Region code (e.g. `nb-eu-germany`). |
+
+These are the same variables the `@norbix.ai/ts` SDK uses.
+
+## Install
+
+The server is published on npm as
+[`@norbix.ai/mcp`](https://www.npmjs.com/package/@norbix.ai/mcp). Nothing to
+install by hand — MCP clients start it with `npx` (Node.js 18 or newer):
+
+```bash
+npx -y @norbix.ai/mcp --help      # usage and env variables
+npx -y @norbix.ai/mcp --version
+```
+
+Or install it globally and use the `norbix-mcp` command:
+
+```bash
+npm install -g @norbix.ai/mcp
+norbix-mcp --help
+```
+
+### Build from source
+
+```bash
+git clone git@github.com:norbix-code/mcp.git && cd mcp
+npm ci
+npm run build
+node dist/index.js --help
+```
+
+## IDE / client setup
+
+### Claude Desktop
+
+`claude_desktop_config.json` → `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "norbix": {
+      "command": "npx",
+      "args": ["-y", "@norbix.ai/mcp"],
+      "env": {
+        "NORBIX_API_KEY": "your-api-key",
+        "NORBIX_HUB_URL": "https://hub.norbix.ai",
+        "NORBIX_PROJECT_ID": "your-project-id"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add norbix \
+  -e NORBIX_API_KEY=your-api-key \
+  -e NORBIX_HUB_URL=https://hub.norbix.ai \
+  -e NORBIX_PROJECT_ID=your-project-id \
+  -- npx -y @norbix.ai/mcp
+```
+
+### Cursor
+
+`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "norbix": {
+      "command": "npx",
+      "args": ["-y", "@norbix.ai/mcp"],
+      "env": {
+        "NORBIX_API_KEY": "your-api-key",
+        "NORBIX_HUB_URL": "https://hub.norbix.ai",
+        "NORBIX_PROJECT_ID": "your-project-id"
+      }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot agent mode)
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "norbix": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@norbix.ai/mcp"],
+      "env": {
+        "NORBIX_API_KEY": "your-api-key",
+        "NORBIX_HUB_URL": "https://hub.norbix.ai"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json` — same JSON shape as Cursor.
+
+> Until the package is published, replace `"command": "npx", "args": [...]`
+> with `"command": "node", "args": ["/path/to/sdks/norbix-mcp/dist/index.js"]`.
+
+## Remote mode (Streamable HTTP)
+
+For a hosted, shared MCP endpoint:
+
+```bash
+NORBIX_HUB_URL=https://hub.norbix.ai norbix-mcp --http --port 3010
+```
+
+- Endpoint: `POST http://host:3010/mcp` (stateless Streamable HTTP).
+- Each request may carry its own key: `Authorization: Bearer <norbix-api-key>`.
+  This overrides `NORBIX_API_KEY`, so one instance can serve many users.
+- Health check: `GET /healthz`.
+
+## Tools
+
+**Discovery + generic call — reaches every endpoint:**
+
+- `norbix_search_endpoints` — find endpoints by keyword (`"push template"`, `"invite user"`, …)
+- `norbix_describe_endpoint` — full request/response field shapes, nested types, enums, and the known subtypes of a polymorphic field
+- `norbix_call_endpoint` — execute any endpoint by name with a JSON body
+- `norbix_set_project` — set/switch the active project
+
+**Curated shortcuts:** `norbix_echo`, `norbix_get_projects`, `norbix_get_project`,
+`norbix_create_project`, `norbix_get_project_environments`,
+`norbix_get_integrations`, `norbix_get_integration`, `norbix_save_integration`,
+`norbix_test_integration`, `norbix_get_marketplace_integrations`,
+`norbix_save_marketplace_integration`, `norbix_get_database_schemas`,
+`norbix_find_documents`, `norbix_insert_document`, `norbix_update_document`,
+`norbix_get_taxonomy_terms`, `norbix_get_roles`, `norbix_get_policies`,
+`norbix_get_logs`, `norbix_list_service_api_keys`.
+
+Typical flow the model follows for anything not curated:
+`norbix_search_endpoints("archive email template")` →
+`norbix_describe_endpoint("archiveEmailTemplate")` →
+`norbix_call_endpoint({ name: "archiveEmailTemplate", body: { id: "…" } })`.
+
+A polymorphic body lists its subtypes. Example — a scheduled task (only
+`EmailCampaign` runs today; `cron` is 5 fields in UTC; `initiatorUserId` is
+you or a project service user): `norbix_describe_endpoint("saveSchedulerTask")`
+shows `types.SchedulerTaskRequest.subtypes.EmailCampaignSchedulerTaskRequest`
+(`type`, `campaign?`, `databaseIntegrationId?`), then
+
+```json
+{ "name": "saveSchedulerTask", "body": {
+  "name": "Weekly digest", "cron": "0 9 * * 1", "initiatorUserId": "usr_…",
+  "isEnabled": true, "stopOnError": false,
+  "task": { "type": "EmailCampaign",
+            "campaign": { "source": "AllUsers", "templateId": "tmpl_…" } } } }
+```
+
+The scheduler module switch (`enableScheduler` / `disableScheduler`) is `PUT`.
+
+## Database tools
+
+Five shortcuts cover the everyday database work. Everything else in the
+Database module (95 endpoints: schemas and drafts, records, taxonomies and
+terms, triggers, aggregates, database integrations) is reached with the
+generic trio.
+
+| Tool | SDK method | Route | Input |
+| --- | --- | --- | --- |
+| `norbix_get_database_schemas` | `hub.database.getDatabaseSchemas` | `GET /{version}/database/schemas` | `body` (paging) |
+| `norbix_find_documents` | `api.database.find` | `GET /{version}/database/collections/{collectionName}` | `body`: `collectionName`, `filter` (JSON string), `sortBy`, `pageSize`, … |
+| `norbix_insert_document` | `api.database.insertOne` | `POST /{version}/database/collections/{collectionName}` | `collectionName`, `document`, `databaseIntegrationId?` |
+| `norbix_update_document` | `api.database.updateOne` | `PUT /{version}/database/collections/{collectionName}/{id}` | `collectionName`, `id`, `update`, `databaseIntegrationId?` |
+| `norbix_get_taxonomy_terms` | `api.database.findTerms` | `GET /{version}/database/taxonomies/{taxonomyName}/terms` | `taxonomyName`, `filter?`, `pageSize?`, `sortDescending?`, `databaseIntegrationId?` |
+
+The Api record endpoints expect the document, the update and the filter as a
+JSON **string**. The three newer shortcuts accept an object or a string and
+send the string, so this works in one call:
+
+```json
+{ "name": "norbix_insert_document", "arguments": {
+  "collectionName": "products", "document": { "title": "Lamp", "price": 12 } } }
+```
+
+```json
+{ "name": "norbix_update_document", "arguments": {
+  "collectionName": "products", "id": "…", "update": { "price": 10 } } }
+```
+
+`update` is the plain field document — the gateway applies it with `$set`.
+A `$` operator in it (`$set`, `$inc`, …) is refused with
+`CM-ERRORS-DATABASE-035`. An update-many or delete-many call with an empty
+filter `{}` is refused (`CM-ERRORS-DATABASE-037`) unless the body also has
+`allRecords: true`.
+
+For anything else, search the `database` group:
+
+- `norbix_search_endpoints({ query: "taxonomy term", group: "database" })`
+- `norbix_describe_endpoint({ name: "saveSchemaTrigger" })`
+- `norbix_call_endpoint({ name: "getDatabaseSchemas", surface: "api" })` —
+  a few names exist on both the Hub (admin plane) and the Api (data plane);
+  pass `surface` for those.
+
+Which tools work depends on the API key's role: the Hub tools need a
+project role with database permissions, the Api tools need permissions on the
+collection. An error answer carries `status`, `code`, `errors` (per field)
+and `payload` (the gateway's body).
+
+## Keeping the endpoint manifest in sync
+
+The tool catalog is generated from the `norbix-js` SDK source and committed
+under `src/manifest/`. After endpoints change (backend regenerates DTOs →
+`norbix-js` runs `npm run generate-endpoints`):
+
+```bash
+npm run generate-manifest && npm run build && npm test
+```
+
+`generate-manifest` reads `../norbix-js`; from a worktree, point it at a
+checkout of the released SDK: `NORBIX_JS_DIR=/path/to/norbix-js npm run generate-manifest`.
+Keep `@norbix.ai/ts` in `package.json` at the version the manifest was made
+from (a test checks every curated tool is in the manifest).
+
+## Tests
+
+```bash
+npm test
+```
+
+Vitest, no network: the server runs over the MCP SDK's in-memory transport
+with a fake Norbix client (or the real `@norbix.ai/ts` client with a fake
+`fetch`).
+
+## Versioning and releases
+
+Every merge to `main` is released to npm by
+[semantic-release](https://semantic-release.gitbook.io/) from the
+conventional-commit messages: `feat:` → minor, `fix:` / `perf:` /
+`refactor:` → patch; `ci:`, `build:`, `test:`, `chore:` do not release.
+**The major version is frozen until the public launch**: a breaking change
+is written as `feat(...)` with a `Breaking: <what>` line in the body (a
+`!:` title or a `BREAKING CHANGE:` footer fails the PR check). The git tag
+is the source of truth for the version; release notes are on the GitHub
+Releases page.
+
+## Security notes
+
+- The server can do exactly what the API key can do — nothing more. Scope the
+  service user's role to what you need (e.g. read-only roles for analysis).
+- Never commit API keys. Use env vars in the MCP client config.
+- In `--http` mode, put the server behind TLS and network controls; the
+  `Authorization` header carries the Norbix API key.

package/dist/client.js

@@ -0,0 +1,70 @@
+/**
+ * Norbix client factory. Configuration comes from NORBIX_* env vars
+ * (NORBIX_API_KEY, NORBIX_HUB_URL, NORBIX_PROJECT_ID, ...) — the same
+ * variables the @norbix.ai/ts SDK reads. On startup we call the Hub /echo
+ * endpoint to discover the rest of the deployment (API URL, regions,
+ * versions) so users only need an API key and the Hub endpoint.
+ */
+import { Norbix } from '@norbix.ai/ts';
+export function requireConfig() {
+    const missing = ['NORBIX_API_KEY', 'NORBIX_HUB_URL'].filter((k) => !process.env[k]);
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variable(s): ${missing.join(', ')}. ` +
+            'Create a service-user API key in the Norbix dashboard ' +
+            '(Membership → Service users) and set NORBIX_HUB_URL to your Hub endpoint.');
+    }
+}
+/**
+ * The SDK constructor requires `projectId`, but account-level work (e.g.
+ * creating the very first project) has none. The transport only sends the
+ * project headers when `cfg.projectId` is set, so when no NORBIX_PROJECT_ID
+ * is configured we construct with a placeholder and clear it. Use the
+ * `norbix_set_project` tool (client.setScope) to pick a project later.
+ */
+function newNorbix(config = {}) {
+    const hasProject = Boolean(process.env.NORBIX_PROJECT_ID);
+    const client = new Norbix({
+        ...config,
+        ...(hasProject ? {} : { projectId: 'unscoped' }),
+    });
+    if (!hasProject) {
+        client.cfg.projectId =
+            undefined;
+    }
+    return client;
+}
+export async function createClient(overrides = {}) {
+    const base = newNorbix(overrides.apiKey ? { apiKey: overrides.apiKey } : {});
+    let echo;
+    try {
+        echo = (await base.hub.echo.echo({}));
+    }
+    catch {
+        // /echo is best-effort discovery; tools still work against the Hub.
+    }
+    // If the API base URL was not configured explicitly, adopt the one the
+    // deployment reports. A user-supplied NORBIX_API_URL always wins.
+    const discoveredApiUrl = !process.env.NORBIX_API_URL && typeof echo?.apiUrl === 'string'
+        ? echo.apiUrl
+        : undefined;
+    const client = discoveredApiUrl
+        ? newNorbix({
+            ...(overrides.apiKey ? { apiKey: overrides.apiKey } : {}),
+            apiUrl: discoveredApiUrl,
+        })
+        : base;
+    return { client, echo };
+}
+/**
+ * Dispatch a call to a generated SDK endpoint method:
+ * client.hub.<group>.<method>(body) / client.api.<group>.<method>(body).
+ */
+export async function invoke(client, surface, group, method, body) {
+    const ns = client[surface];
+    const mod = ns?.[group];
+    const fn = mod?.[method];
+    if (typeof fn !== 'function') {
+        throw new Error(`Unknown endpoint: ${surface}.${group}.${method}`);
+    }
+    return fn(body ?? {});
+}

package/dist/http.js

@@ -0,0 +1,62 @@
+/**
+ * Streamable HTTP transport (remote MCP). Stateless: every POST /mcp gets a
+ * fresh server + transport, so the endpoint scales horizontally and needs no
+ * session store.
+ *
+ * Auth: `Authorization: Bearer <norbix-api-key>` on each request wins over
+ * the NORBIX_API_KEY env var. This lets one hosted instance serve many users,
+ * each with their own service-user key.
+ */
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+import { createClient } from './client.js';
+import { buildServer } from './server.js';
+export async function startHttp(port) {
+    const app = express();
+    app.use(express.json({ limit: '4mb' }));
+    app.get('/healthz', (_req, res) => {
+        res.json({ ok: true, name: 'norbix-mcp' });
+    });
+    app.post('/mcp', async (req, res) => {
+        try {
+            const auth = req.headers.authorization;
+            const apiKey = auth?.replace(/^Bearer\s+/i, '').trim() || undefined;
+            const handle = await createClient(apiKey ? { apiKey } : {});
+            const server = buildServer(handle);
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            res.on('close', () => {
+                void transport.close();
+                void server.close();
+            });
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (e) {
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32603, message: e.message },
+                    id: null,
+                });
+            }
+        }
+    });
+    // Stateless mode: no server-initiated streams, no sessions to delete.
+    const reject = (_req, res) => {
+        res.status(405).json({
+            jsonrpc: '2.0',
+            error: { code: -32000, message: 'Method not allowed (stateless server).' },
+            id: null,
+        });
+    };
+    app.get('/mcp', reject);
+    app.delete('/mcp', reject);
+    await new Promise((resolve) => {
+        app.listen(port, () => {
+            console.error(`norbix-mcp listening on http://localhost:${port}/mcp`);
+            resolve();
+        });
+    });
+}

package/dist/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Norbix MCP server.
+ *
+ *   norbix-mcp                 stdio transport (Claude, Cursor, VS Code, …)
+ *   norbix-mcp --http          Streamable HTTP on port 3010 (remote MCP)
+ *   norbix-mcp --http --port N Streamable HTTP on port N
+ *
+ * Required env: NORBIX_API_KEY, NORBIX_HUB_URL.
+ * Optional env: NORBIX_PROJECT_ID, NORBIX_ACCOUNT_ID, NORBIX_API_URL,
+ *               NORBIX_ENV, NORBIX_REGION (same vars as the @norbix.ai/ts SDK).
+ */
+import { createRequire } from 'node:module';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createClient, requireConfig } from './client.js';
+import { startHttp } from './http.js';
+import { buildServer } from './server.js';
+const HELP = `Norbix MCP server
+
+Usage:
+  norbix-mcp                   stdio transport (Claude, Cursor, VS Code, ...)
+  norbix-mcp --http [--port N] Streamable HTTP (default port 3010)
+  norbix-mcp --help            show this text
+  norbix-mcp --version         show the version
+
+Required env: NORBIX_API_KEY, NORBIX_HUB_URL
+Optional env: NORBIX_PROJECT_ID, NORBIX_ACCOUNT_ID, NORBIX_API_URL,
+              NORBIX_ENV, NORBIX_REGION
+
+Docs: https://github.com/norbix-code/mcp#readme`;
+function packageVersion() {
+    // dist/index.js -> ../package.json (npm always ships package.json).
+    const pkg = createRequire(import.meta.url)('../package.json');
+    return pkg.version ?? 'unknown';
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log(HELP);
+        return;
+    }
+    if (args.includes('--version') || args.includes('-v')) {
+        console.log(packageVersion());
+        return;
+    }
+    const http = args.includes('--http');
+    const portIdx = args.indexOf('--port');
+    const port = portIdx >= 0 ? Number(args[portIdx + 1]) : 3010;
+    if (http) {
+        // In HTTP mode the key may arrive per request; env config is a fallback.
+        await startHttp(Number.isFinite(port) ? port : 3010);
+        return;
+    }
+    requireConfig();
+    const handle = await createClient();
+    if (handle.echo) {
+        console.error(`norbix-mcp: connected to ${process.env.NORBIX_HUB_URL} ` +
+            `(hub ${String(handle.echo.hubVersion ?? '?')}, api ${String(handle.echo.apiVersion ?? '?')})`);
+    }
+    else {
+        console.error('norbix-mcp: warning — /echo discovery failed; check NORBIX_HUB_URL and network. Tools will still try to call the Hub.');
+    }
+    const server = buildServer(handle);
+    await server.connect(new StdioServerTransport());
+    console.error('norbix-mcp: ready (stdio)');
+}
+main().catch((e) => {
+    console.error(`norbix-mcp: fatal — ${e.message}`);
+    process.exit(1);
+});