@norbix.ai/mcp 0.0.0-stage → 0.2.1

package/dist/manifest.js

@@ -0,0 +1,94 @@
+/**
+ * Loads the committed endpoint manifest + DTO catalogs generated by
+ * scripts/generate-manifest.mjs from the norbix-js SDK source.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'manifest');
+function load(file) {
+    return JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+}
+export const endpoints = load('endpoints.json');
+export const dtos = {
+    hub: load('dtos.hub.json'),
+    api: load('dtos.api.json'),
+};
+/** Find an endpoint by SDK method name or request DTO name (case-insensitive). */
+export function resolveEndpoint(name, surface) {
+    const n = name.toLowerCase();
+    return endpoints.filter((e) => (!surface || e.surface === surface) &&
+        (e.method.toLowerCase() === n || e.requestDto.toLowerCase() === n));
+}
+/** Collect a DTO's own + inherited fields (base-class chain). */
+export function collectFields(surface, dtoName) {
+    const catalog = dtos[surface];
+    const fields = [];
+    const chain = [];
+    const seen = new Set();
+    let cur = dtoName;
+    while (cur && !seen.has(cur)) {
+        seen.add(cur);
+        const shape = catalog[cur];
+        if (!shape || ('enum' in shape && shape.enum))
+            break;
+        chain.push(cur);
+        for (const f of shape.fields) {
+            if (!fields.some((x) => x.name === f.name))
+                fields.push(f);
+        }
+        cur = shape.base;
+    }
+    return { fields, chain };
+}
+/**
+ * The known subtypes of a polymorphic base type ("extends" in the contract),
+ * e.g. SchedulerTaskRequest → EmailCampaignSchedulerTaskRequest.
+ */
+export function subtypesOf(surface, base) {
+    return Object.entries(dtos[surface])
+        .filter(([, s]) => !('enum' in s && s.enum) && s.base === base)
+        .map(([name]) => name)
+        .sort();
+}
+const fieldText = (x) => `${x.name}${x.optional ? '?' : ''}: ${x.type}`;
+/**
+ * Shallow expansion of complex field types (one level), for describe output.
+ * A base type with known subtypes also lists each subtype's own fields under
+ * `subtypes` — send one of them, with its `type` discriminator — and the
+ * types of those subtype fields are expanded too (one more level), so a
+ * polymorphic body such as SaveSchedulerTaskRequest.task is fully visible.
+ */
+export function expandTypes(surface, fields) {
+    const catalog = dtos[surface];
+    const out = {};
+    const expand = (list) => {
+        const reached = [];
+        for (const f of list) {
+            const bare = f.type.replace(/\[\]$/, '').trim();
+            const shape = catalog[bare];
+            if (!shape || bare in out)
+                continue;
+            if ('enum' in shape && shape.enum) {
+                out[bare] = { enum: shape.values };
+                continue;
+            }
+            const entry = {
+                fields: shape.fields.map(fieldText),
+            };
+            const subs = subtypesOf(surface, bare);
+            if (subs.length > 0) {
+                entry.subtypes = {};
+                for (const sub of subs) {
+                    const own = catalog[sub].fields;
+                    entry.subtypes[sub] = own.map(fieldText);
+                    reached.push(...own);
+                }
+            }
+            out[bare] = entry;
+        }
+        return reached;
+    };
+    expand(expand(fields));
+    return out;
+}

package/dist/server.js

@@ -0,0 +1,281 @@
+/**
+ * Builds the Norbix MCP server: curated tools for the most common Hub/API
+ * work, plus a generic search → describe → call trio that reaches every
+ * one of the Norbix endpoints in the manifest (src/manifest/endpoints.json).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { invoke } from './client.js';
+import { collectFields, endpoints, expandTypes, resolveEndpoint, } from './manifest.js';
+const MAX_RESULT_CHARS = 60_000;
+function json(data) {
+    let text = JSON.stringify(data, null, 2) ?? 'null';
+    if (text.length > MAX_RESULT_CHARS) {
+        text =
+            text.slice(0, MAX_RESULT_CHARS) +
+                `\n… truncated (${text.length} chars total). Narrow the request (pageSize, filter) to see more.`;
+    }
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * Turn a thrown error into an MCP tool error. A NorbixError (@norbix.ai/ts)
+ * carries status, code, the field errors and the raw body; `payload` is the
+ * older name of the body and is kept for clients that read it.
+ */
+export function err(e) {
+    const anyE = e;
+    const errors = Array.isArray(anyE?.fieldErrors) && anyE.fieldErrors.length > 0
+        ? anyE.fieldErrors
+        : undefined;
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: anyE?.message ?? String(e),
+                    status: anyE?.status,
+                    code: anyE?.code,
+                    errors,
+                    payload: anyE?.raw ?? anyE?.payload,
+                }, null, 2),
+            },
+        ],
+    };
+}
+/** Human-readable request-field summary for a tool description. */
+function fieldSummary(ep, max = 20) {
+    const { fields } = collectFields(ep.surface, ep.requestDto);
+    const shown = fields
+        .slice(0, max)
+        .map((f) => `${f.name}${f.optional ? '?' : ''}: ${f.type}`)
+        .join(', ');
+    const more = fields.length > max ? `, … +${fields.length - max} more` : '';
+    return shown ? ` Body fields: ${shown}${more}.` : '';
+}
+const bodySchema = {
+    body: z
+        .record(z.unknown())
+        .optional()
+        .describe('Request body (JSON object matching the request DTO fields).'),
+};
+export const curated = [
+    { name: 'norbix_echo', surface: 'hub', group: 'echo', method: 'echo', description: 'Get Norbix deployment info: release, Hub/API URLs and versions, regions, license.' },
+    { name: 'norbix_get_projects', surface: 'hub', group: 'account', method: 'getProjects', description: 'List all projects in the account.' },
+    { name: 'norbix_get_project', surface: 'hub', group: 'account', method: 'getProject', description: 'Get one project by id.' },
+    { name: 'norbix_create_project', surface: 'hub', group: 'account', method: 'createProject', description: 'Create a new project.' },
+    { name: 'norbix_get_project_environments', surface: 'hub', group: 'account', method: 'getProjectEnvironments', description: 'List the environments of a project.' },
+    { name: 'norbix_get_integrations', surface: 'hub', group: 'code', method: 'getCodeIntegrations', description: 'List code integrations of the project.' },
+    { name: 'norbix_get_integration', surface: 'hub', group: 'code', method: 'getCodeIntegration', description: 'Get one code integration.' },
+    { name: 'norbix_save_integration', surface: 'hub', group: 'code', method: 'saveCodeIntegration', description: 'Create or update a code integration.' },
+    { name: 'norbix_test_integration', surface: 'hub', group: 'code', method: 'testCodeIntegration', description: 'Test a code integration.' },
+    { name: 'norbix_get_marketplace_integrations', surface: 'hub', group: 'code', method: 'getMarketplaceIntegrations', description: 'List marketplace integrations of the project.' },
+    { name: 'norbix_save_marketplace_integration', surface: 'hub', group: 'code', method: 'saveMarketplaceIntegration', description: 'Create or update a marketplace integration.' },
+    { name: 'norbix_get_database_schemas', surface: 'hub', group: 'database', method: 'getDatabaseSchemas', description: 'List database collection schemas of the project.' },
+    { name: 'norbix_find_documents', surface: 'api', group: 'database', method: 'find', description: 'Query documents in a database collection (filter, sort, projection, paging).' },
+    { name: 'norbix_get_roles', surface: 'hub', group: 'membership', method: 'getRoles', description: 'List membership roles of the project.' },
+    { name: 'norbix_get_policies', surface: 'hub', group: 'membership', method: 'getPolicies', description: 'List membership policies of the project.' },
+    { name: 'norbix_get_logs', surface: 'hub', group: 'logs', method: 'getLogs', description: 'Query project logs.' },
+    { name: 'norbix_list_service_api_keys', surface: 'hub', group: 'membership', method: 'listServiceUserApiKeys', description: 'List API keys of a service user.' },
+];
+export function buildServer(handle) {
+    const server = new McpServer({ name: 'norbix', version: '0.1.0' });
+    // --- Curated tools -------------------------------------------------------
+    for (const t of curated) {
+        const ep = endpoints.find((e) => e.surface === t.surface && e.group === t.group && e.method === t.method);
+        const desc = t.description +
+            (ep ? ` [${ep.verb} ${ep.path}]` : '') +
+            (ep ? fieldSummary(ep) : '');
+        server.registerTool(t.name, { title: t.name, description: desc, inputSchema: bodySchema }, async ({ body }) => {
+            try {
+                return json(await invoke(handle.client, t.surface, t.group, t.method, body ?? {}));
+            }
+            catch (e) {
+                return err(e);
+            }
+        });
+    }
+    // --- Database shortcuts with typed input ---------------------------------
+    // The Api record endpoints take the document / update as a JSON *string*;
+    // a model naturally sends an object. These shortcuts accept either and
+    // send the string, so the most common data tasks work in one call instead
+    // of search → describe → call (and a failed first try).
+    const asJson = (v) => (typeof v === 'string' ? v : JSON.stringify(v));
+    const jsonValue = z.union([z.string(), z.record(z.unknown()), z.array(z.unknown())]);
+    const integrationId = z
+        .string()
+        .optional()
+        .describe('Database integration id; omit for the project default database.');
+    server.registerTool('norbix_insert_document', {
+        title: 'norbix_insert_document',
+        description: 'Insert one document into a database collection. Returns the new id. [POST /{version}/database/collections/{collectionName}]',
+        inputSchema: {
+            collectionName: z.string().describe('Collection (schema) name, e.g. "products".'),
+            document: jsonValue.describe('The document: a JSON object (or a JSON string).'),
+            databaseIntegrationId: integrationId,
+        },
+    }, async ({ collectionName, document, databaseIntegrationId }) => {
+        try {
+            return json(await invoke(handle.client, 'api', 'database', 'insertOne', {
+                collectionName,
+                document: asJson(document),
+                ...(databaseIntegrationId ? { databaseIntegrationId } : {}),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.registerTool('norbix_update_document', {
+        title: 'norbix_update_document',
+        description: 'Update one document by id. Send only the fields to change as a plain document, e.g. { "price": 10 }; the gateway applies it with $set. Update operators ($set, $inc, $unset, …) are refused (CM-ERRORS-DATABASE-035). [PUT /{version}/database/collections/{collectionName}/{id}]',
+        inputSchema: {
+            collectionName: z.string().describe('Collection (schema) name.'),
+            id: z.string().describe('Document id.'),
+            update: jsonValue.describe('The fields to change as a plain document, e.g. { "field": "value" } (object or JSON string). No $ operators.'),
+            databaseIntegrationId: integrationId,
+        },
+    }, async ({ collectionName, id, update, databaseIntegrationId }) => {
+        try {
+            return json(await invoke(handle.client, 'api', 'database', 'updateOne', {
+                collectionName,
+                id,
+                update: asJson(update),
+                ...(databaseIntegrationId ? { databaseIntegrationId } : {}),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.registerTool('norbix_get_taxonomy_terms', {
+        title: 'norbix_get_taxonomy_terms',
+        description: 'List the terms of a taxonomy (categories, tags), with an optional MongoDB filter and paging. [GET /{version}/database/taxonomies/{taxonomyName}/terms]',
+        inputSchema: {
+            taxonomyName: z.string().describe('Taxonomy name, e.g. "categories".'),
+            filter: jsonValue.optional().describe('MongoDB filter on the terms (object or JSON string).'),
+            pageSize: z.number().int().min(1).max(1000).optional(),
+            sortDescending: z.boolean().optional(),
+            databaseIntegrationId: integrationId,
+        },
+    }, async ({ taxonomyName, filter, pageSize, sortDescending, databaseIntegrationId }) => {
+        try {
+            return json(await invoke(handle.client, 'api', 'database', 'findTerms', {
+                taxonomyName,
+                sortDescending: sortDescending ?? false,
+                ...(filter !== undefined ? { filter: asJson(filter) } : {}),
+                ...(pageSize !== undefined ? { pageSize } : {}),
+                ...(databaseIntegrationId ? { databaseIntegrationId } : {}),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    // --- Project scope --------------------------------------------------------
+    server.registerTool('norbix_set_project', {
+        title: 'Set active project',
+        description: 'Set (or switch) the project that later calls target. Sent as the project header on every request. Use norbix_get_projects to find project ids.',
+        inputSchema: {
+            projectId: z.string().describe('The project id to work in.'),
+            accountId: z.string().optional(),
+        },
+    }, async ({ projectId, accountId }) => {
+        handle.client.setScope({ projectId, ...(accountId ? { accountId } : {}) });
+        return json({ ok: true, projectId });
+    });
+    // --- Generic trio: search → describe → call ------------------------------
+    server.registerTool('norbix_search_endpoints', {
+        title: 'Search Norbix endpoints',
+        description: `Search all Norbix Hub/API endpoints (${endpoints.length}) by keyword.` +
+            ' Returns method names to use with norbix_describe_endpoint and norbix_call_endpoint. Groups: ' +
+            [...new Set(endpoints.map((e) => e.group))].sort().join(', ') +
+            '.',
+        inputSchema: {
+            query: z.string().describe('Keyword(s), e.g. "push template", "invite user", "webhook".'),
+            surface: z.enum(['hub', 'api']).optional().describe('hub = admin/dashboard plane, api = data plane.'),
+            group: z.string().optional().describe('Endpoint group, e.g. account, code, database, membership, notifications.'),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+    }, async ({ query, surface, group, limit }) => {
+        const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+        const scored = endpoints
+            .filter((e) => (!surface || e.surface === surface) && (!group || e.group === group))
+            .map((e) => {
+            const hay = `${e.method} ${e.requestDto} ${e.path} ${e.group}`.toLowerCase();
+            const score = words.reduce((s, w) => s + (hay.includes(w) ? 1 : 0), 0);
+            return { e, score };
+        })
+            .filter((x) => x.score === words.length || x.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit ?? 25)
+            .map(({ e }) => ({
+            surface: e.surface,
+            group: e.group,
+            method: e.method,
+            requestDto: e.requestDto,
+            route: `${e.verb} ${e.path}`,
+        }));
+        return json(scored);
+    });
+    server.registerTool('norbix_describe_endpoint', {
+        title: 'Describe a Norbix endpoint',
+        description: 'Show the full request/response shape of an endpoint (all body fields, inherited ones included, plus nested types and enums). A polymorphic type lists its known subtypes under types.<Type>.subtypes — send one of them with its type discriminator (e.g. task: { type: "EmailCampaign", campaign: {...} }). Use before norbix_call_endpoint.',
+        inputSchema: {
+            name: z.string().describe('SDK method name (e.g. createProject) or request DTO name (e.g. CreateProjectRequest).'),
+            surface: z.enum(['hub', 'api']).optional(),
+        },
+    }, async ({ name, surface }) => {
+        const matches = resolveEndpoint(name, surface);
+        if (matches.length === 0) {
+            return err(new Error(`No endpoint named "${name}". Use norbix_search_endpoints first.`));
+        }
+        return json(matches.map((ep) => {
+            const req = collectFields(ep.surface, ep.requestDto);
+            const res = collectFields(ep.surface, ep.responseDto);
+            return {
+                surface: ep.surface,
+                group: ep.group,
+                method: ep.method,
+                route: `${ep.verb} ${ep.path}`,
+                scope: ep.scope,
+                request: {
+                    dto: ep.requestDto,
+                    fields: req.fields.map((f) => `${f.name}${f.optional ? '?' : ''}: ${f.type}`),
+                },
+                response: {
+                    dto: ep.responseDto,
+                    fields: res.fields.map((f) => `${f.name}${f.optional ? '?' : ''}: ${f.type}`),
+                },
+                types: expandTypes(ep.surface, [...req.fields, ...res.fields]),
+            };
+        }));
+    });
+    server.registerTool('norbix_call_endpoint', {
+        title: 'Call any Norbix endpoint',
+        description: 'Execute any Norbix Hub/API endpoint by SDK method name or request DTO name. The API key’s permissions decide what is allowed. Use norbix_search_endpoints + norbix_describe_endpoint to find the right name and body shape.',
+        inputSchema: {
+            name: z.string().describe('SDK method name (e.g. sendInviteToTeamMember) or request DTO name.'),
+            surface: z.enum(['hub', 'api']).optional().describe('Required only when the name exists on both surfaces.'),
+            body: z.record(z.unknown()).optional().describe('Request body matching the request DTO fields.'),
+        },
+    }, async ({ name, surface, body }) => {
+        const matches = resolveEndpoint(name, surface);
+        if (matches.length === 0) {
+            return err(new Error(`No endpoint named "${name}". Use norbix_search_endpoints first.`));
+        }
+        if (matches.length > 1) {
+            return err(new Error(`Ambiguous name "${name}" — matches: ` +
+                matches.map((m) => `${m.surface}.${m.group}.${m.method}`).join(', ') +
+                '. Pass surface to disambiguate.'));
+        }
+        const ep = matches[0];
+        try {
+            return json(await invoke(handle.client, ep.surface, ep.group, ep.method, body ?? {}));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@norbix.ai/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Norbix MCP server — manage projects, integrations, databases, membership, notifications and every other Norbix Hub/API endpoint from Claude, Cursor, VS Code, Windsurf or any MCP client.",
+  "author": "UAB Isidos",
+  "license": "MIT",
+  "homepage": "https://norbix.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/norbix-code/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/norbix-code/mcp/issues"
+  },
+  "keywords": [
+    "norbix",
+    "mcp",
+    "model-context-protocol",
+    "baas",
+    "ai",
+    "claude",
+    "cursor"
+  ],
+  "type": "module",
+  "bin": {
+    "norbix-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "generate-manifest": "node scripts/generate-manifest.mjs",
+    "build": "tsc && node -e \"const fs=require('fs');fs.rmSync('dist/manifest',{recursive:true,force:true});fs.cpSync('src/manifest','dist/manifest',{recursive:true});fs.chmodSync('dist/index.js',0o755)\"",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "start:http": "node dist/index.js --http",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "release:dry": "semantic-release --dry-run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@norbix.ai/ts": "^4.11.0",
+    "express": "^4.21.2",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.10",
+    "@semantic-release/npm": "^13.2.0",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "semantic-release": "^25.0.9",
+    "typescript": "^5.7.0",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}