@nubase_ai/mcp-bridge 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @nubase_ai/mcp-bridge
+
+stdio MCP bridge for Nubase. Use it when Codex, Claude Code, Cursor, IDEA, or another local MCP client needs Nubase tools.
+
+## Install
+
+```bash
+npx @nubase_ai/mcp-bridge
+```
+
+For local development inside the Nubase repository:
+
+```bash
+cd frontend
+pnpm --filter @nubase_ai/mcp-bridge build
+node packages/mcp-bridge/dist/src/index.js
+```
+
+## MCP Config
+
+```json
+{
+  "mcpServers": {
+    "nubase": {
+      "command": "npx",
+      "args": ["@nubase_ai/mcp-bridge"],
+      "env": {
+        "NUBASE_URL": "http://localhost:9999",
+        "NUBASE_PROJECT_KEY": "YOUR_NUBASE_PROJECT_KEY",
+        "NUBASE_AGENT_ID": "claude-code"
+      }
+    }
+  }
+}
+```
+
+## Context Injection
+
+The bridge injects user and session context from environment variables:
+
+```bash
+NUBASE_URL=http://localhost:9999
+NUBASE_PROJECT_KEY=YOUR_NUBASE_PROJECT_KEY
+NUBASE_USER_JWT=USER_ACCESS_TOKEN
+NUBASE_USER_ID=USER_UUID
+NUBASE_AGENT_ID=codex
+NUBASE_RUN_ID=feature-123
+```
+
+Tool arguments can override `userId`, `agentId`, and `runId` for one call. API keys and JWTs stay in the bridge process environment and are not exposed as tool arguments.
+
+## SQL Safety
+
+SQL execution is disabled by default:
+
+```bash
+NUBASE_ALLOW_SQL_EXECUTE=true
+NUBASE_ALLOW_DANGEROUS_SQL=false
+```
+
+Use `sql_dry_run` before `sql_execute`. Dangerous SQL remains blocked unless `NUBASE_ALLOW_DANGEROUS_SQL=true`.
+
+## Tools
+
+- `nubase_capabilities`
+- `nubase_instructions`
+- `memory_context`
+- `memory_search`
+- `memory_write`
+- `rest_select`
+- `sql_dry_run`
+- `sql_execute`
+
+## Publish
+
+```bash
+pnpm --filter @nubase_ai/mcp-bridge typecheck
+pnpm --filter @nubase_ai/mcp-bridge build
+pnpm --filter @nubase_ai/mcp-bridge test
+pnpm --filter @nubase_ai/mcp-bridge pack:check
+cd packages/mcp-bridge
+npm publish --access public
+```

package/dist/src/config.d.ts

@@ -0,0 +1,11 @@
+export interface BridgeConfig {
+    nubaseUrl: string;
+    projectKey: string;
+    userJwt?: string;
+    agentId?: string;
+    userId?: string;
+    runId?: string;
+    allowSqlExecute: boolean;
+    allowDangerousSql: boolean;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): BridgeConfig;

package/dist/src/config.js

@@ -0,0 +1,23 @@
+export function loadConfig(env = process.env) {
+    const nubaseUrl = stripTrailingSlash(env.NUBASE_URL || 'http://localhost:9999');
+    const projectKey = env.NUBASE_PROJECT_KEY || env.NUBASE_API_KEY || '';
+    return {
+        nubaseUrl,
+        projectKey,
+        userJwt: blankToUndefined(env.NUBASE_USER_JWT),
+        agentId: blankToUndefined(env.NUBASE_AGENT_ID),
+        userId: blankToUndefined(env.NUBASE_USER_ID),
+        runId: blankToUndefined(env.NUBASE_RUN_ID),
+        allowSqlExecute: truthy(env.NUBASE_ALLOW_SQL_EXECUTE),
+        allowDangerousSql: truthy(env.NUBASE_ALLOW_DANGEROUS_SQL),
+    };
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, '');
+}
+function blankToUndefined(value) {
+    return value && value.trim() ? value.trim() : undefined;
+}
+function truthy(value) {
+    return ['1', 'true', 'yes', 'on'].includes((value || '').toLowerCase());
+}

package/dist/src/context.d.ts

@@ -0,0 +1,13 @@
+import type { BridgeConfig } from './config.js';
+export interface ScopeArgs {
+    userId?: string;
+    agentId?: string;
+    runId?: string;
+}
+export interface ResolvedScope {
+    userId?: string;
+    agentId?: string;
+    runId?: string;
+}
+export declare function resolveScope(config: BridgeConfig, args?: ScopeArgs): ResolvedScope;
+export declare function withScope<T extends Record<string, unknown>>(config: BridgeConfig, args: T & ScopeArgs): T & ResolvedScope;

package/dist/src/context.js

@@ -0,0 +1,11 @@
+export function resolveScope(config, args = {}) {
+    return {
+        userId: args.userId || config.userId,
+        agentId: args.agentId || config.agentId,
+        runId: args.runId || config.runId,
+    };
+}
+export function withScope(config, args) {
+    const scope = resolveScope(config, args);
+    return Object.fromEntries(Object.entries({ ...args, ...scope }).filter(([, value]) => value !== undefined && value !== ''));
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/index.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { loadConfig } from './config.js';
+import { McpStdioServer } from './mcp-stdio.js';
+import { NubaseClient } from './nubase-client.js';
+import { callTool, TOOLS } from './tools.js';
+const config = loadConfig();
+const client = new NubaseClient(config);
+const server = new McpStdioServer(async (request) => {
+    switch (request.method) {
+        case 'initialize':
+            return {
+                protocolVersion: request.params?.protocolVersion ?? '2024-11-05',
+                capabilities: { tools: {} },
+                serverInfo: { name: '@nubase_ai/mcp-bridge', version: '0.1.0' },
+            };
+        case 'notifications/initialized':
+            return null;
+        case 'tools/list':
+            return {
+                tools: TOOLS.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                })),
+            };
+        case 'tools/call': {
+            const name = request.params?.name;
+            const args = request.params?.arguments ?? {};
+            const result = await callTool(name, args, config, client);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`Unsupported method: ${request.method}`);
+    }
+});
+server.start();

package/dist/src/mcp-stdio.d.ts

@@ -0,0 +1,19 @@
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number;
+    method: string;
+    params?: any;
+}
+type Handler = (request: JsonRpcRequest) => Promise<unknown> | unknown;
+export declare class McpStdioServer {
+    private readonly handler;
+    private readonly events;
+    private buffer;
+    constructor(handler: Handler);
+    start(): void;
+    private onData;
+    private handleMessage;
+    private readMessage;
+    private write;
+}
+export {};

package/dist/src/mcp-stdio.js

@@ -0,0 +1,71 @@
+import { EventEmitter } from 'node:events';
+import { stdin, stdout } from 'node:process';
+export class McpStdioServer {
+    handler;
+    events = new EventEmitter();
+    buffer = Buffer.alloc(0);
+    constructor(handler) {
+        this.handler = handler;
+    }
+    start() {
+        stdin.on('data', (chunk) => this.onData(chunk));
+        stdin.resume();
+    }
+    onData(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        while (true) {
+            const next = this.readMessage();
+            if (!next)
+                return;
+            this.handleMessage(next).catch((error) => {
+                this.write({
+                    jsonrpc: '2.0',
+                    id: next.id ?? null,
+                    error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
+                });
+            });
+        }
+    }
+    async handleMessage(request) {
+        if (request.id === undefined) {
+            await this.handler(request);
+            return;
+        }
+        try {
+            const result = await this.handler(request);
+            this.write({ jsonrpc: '2.0', id: request.id, result });
+        }
+        catch (error) {
+            this.write({
+                jsonrpc: '2.0',
+                id: request.id,
+                error: {
+                    code: -32603,
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+    }
+    readMessage() {
+        const headerEnd = this.buffer.indexOf('\r\n\r\n');
+        if (headerEnd === -1)
+            return null;
+        const header = this.buffer.subarray(0, headerEnd).toString('utf8');
+        const match = /Content-Length:\s*(\d+)/i.exec(header);
+        if (!match) {
+            throw new Error('Missing Content-Length header');
+        }
+        const length = Number(match[1]);
+        const bodyStart = headerEnd + 4;
+        const bodyEnd = bodyStart + length;
+        if (this.buffer.length < bodyEnd)
+            return null;
+        const body = this.buffer.subarray(bodyStart, bodyEnd).toString('utf8');
+        this.buffer = this.buffer.subarray(bodyEnd);
+        return JSON.parse(body);
+    }
+    write(message) {
+        const body = JSON.stringify(message);
+        stdout.write(`Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`);
+    }
+}

package/dist/src/nubase-client.d.ts

@@ -0,0 +1,19 @@
+import type { BridgeConfig } from './config.js';
+export declare class NubaseClient {
+    private readonly config;
+    constructor(config: BridgeConfig);
+    capabilities(): Promise<any>;
+    instructions(): Promise<any>;
+    memoryContext(args: Record<string, unknown>): Promise<any>;
+    memorySearch(args: Record<string, unknown>): Promise<any>;
+    memoryWrite(args: Record<string, unknown>): Promise<any>;
+    restSelect(args: Record<string, unknown>): Promise<any>;
+    sqlDryRun(args: Record<string, unknown>): {
+        success: boolean;
+        risk: import("./sql-risk.js").SqlRisk;
+        statementCount: number;
+        executable: boolean;
+    };
+    sqlExecute(args: Record<string, unknown>): Promise<any>;
+    private request;
+}

package/dist/src/nubase-client.js

@@ -0,0 +1,117 @@
+import { classifySql, countStatements } from './sql-risk.js';
+export class NubaseClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    capabilities() {
+        return this.request('/agent/v1/capabilities');
+    }
+    instructions() {
+        return this.request('/agent/v1/instructions');
+    }
+    memoryContext(args) {
+        return this.request('/mem/v1/search', {
+            method: 'POST',
+            body: {
+                userId: args.userId,
+                agentId: args.agentId,
+                runId: args.runId,
+                query: args.task || args.query,
+                topK: args.topK ?? 8,
+            },
+        });
+    }
+    memorySearch(args) {
+        return this.request('/mem/v1/search', { method: 'POST', body: args });
+    }
+    memoryWrite(args) {
+        return this.request('/mem/v1/memories', {
+            method: 'POST',
+            body: {
+                userId: args.userId,
+                agentId: args.agentId,
+                runId: args.runId,
+                infer: args.infer ?? true,
+                messages: [{ role: 'user', content: args.content }],
+            },
+        });
+    }
+    restSelect(args) {
+        const table = requiredString(args.table, 'table');
+        const query = typeof args.query === 'string' && args.query ? args.query : 'select=*';
+        return this.request(`/rest/v1/${encodeURIComponent(table)}?${query}`);
+    }
+    sqlDryRun(args) {
+        const sql = requiredString(args.sql, 'sql');
+        const risk = classifySql(sql);
+        return {
+            success: true,
+            risk,
+            statementCount: countStatements(sql),
+            executable: risk !== 'DANGEROUS',
+        };
+    }
+    async sqlExecute(args) {
+        const sql = requiredString(args.sql, 'sql');
+        const dryRun = this.sqlDryRun({ sql });
+        if (!this.config.allowSqlExecute) {
+            return {
+                success: false,
+                error: 'SQL execution is disabled. Set NUBASE_ALLOW_SQL_EXECUTE=true to enable it.',
+                dryRun,
+            };
+        }
+        if (dryRun.risk === 'DANGEROUS' && !this.config.allowDangerousSql) {
+            return {
+                success: false,
+                error: 'Dangerous SQL is blocked. Set NUBASE_ALLOW_DANGEROUS_SQL=true to allow it.',
+                dryRun,
+            };
+        }
+        const result = await this.request('/auth/v1/admin/sql/execute', {
+            method: 'POST',
+            body: { query: sql },
+        });
+        return { risk: dryRun.risk, ...result };
+    }
+    async request(path, options = {}) {
+        if (!this.config.projectKey) {
+            throw new Error('Missing NUBASE_PROJECT_KEY or NUBASE_API_KEY.');
+        }
+        const headers = {
+            apikey: this.config.projectKey,
+            'Content-Type': 'application/json',
+        };
+        if (this.config.userJwt) {
+            headers.Authorization = `Bearer ${this.config.userJwt}`;
+        }
+        const response = await fetch(`${this.config.nubaseUrl}${path}`, {
+            method: options.method || 'GET',
+            headers,
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        });
+        const text = await response.text();
+        const data = parseResponse(text);
+        if (!response.ok) {
+            throw new Error(typeof data === 'string' ? data : JSON.stringify(data));
+        }
+        return data;
+    }
+}
+function parseResponse(text) {
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function requiredString(value, name) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`${name} is required`);
+    }
+    return value;
+}

package/dist/src/sql-risk.d.ts

@@ -0,0 +1,3 @@
+export type SqlRisk = 'UNKNOWN' | 'READ' | 'DATA_WRITE' | 'SCHEMA_WRITE' | 'DANGEROUS';
+export declare function classifySql(sql: string | undefined): SqlRisk;
+export declare function countStatements(sql: string | undefined): number;

package/dist/src/sql-risk.js

@@ -0,0 +1,51 @@
+export function classifySql(sql) {
+    const statements = splitStatements(sql);
+    if (statements.length === 0)
+        return 'UNKNOWN';
+    return statements.reduce((highest, statement) => maxRisk(highest, classifyStatement(statement)), 'UNKNOWN');
+}
+export function countStatements(sql) {
+    return splitStatements(sql).length;
+}
+function classifyStatement(statement) {
+    const normalized = statement
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/--.*$/gm, ' ')
+        .trim()
+        .replace(/\s+/g, ' ')
+        .toLowerCase();
+    if (!normalized)
+        return 'UNKNOWN';
+    if (startsWithAny(normalized, ['drop ', 'truncate ', 'reindex ', 'vacuum full', 'cluster ']))
+        return 'DANGEROUS';
+    if (/^delete\s+from\s+[^\s;]+\s*$/.test(normalized))
+        return 'DANGEROUS';
+    if (startsWithAny(normalized, ['create ', 'alter ', 'grant ', 'revoke ', 'comment ', 'security label '])) {
+        return 'SCHEMA_WRITE';
+    }
+    if (startsWithAny(normalized, ['insert ', 'update ', 'delete ', 'merge ', 'copy ', 'call ']))
+        return 'DATA_WRITE';
+    if (startsWithAny(normalized, ['select ', 'with ', 'show ', 'explain ', 'describe ']))
+        return 'READ';
+    return 'UNKNOWN';
+}
+function splitStatements(sql) {
+    if (!sql || !sql.trim())
+        return [];
+    return sql.split(';').map((s) => s.trim()).filter(Boolean);
+}
+function startsWithAny(value, prefixes) {
+    return prefixes.some((prefix) => value.startsWith(prefix));
+}
+function maxRisk(left, right) {
+    return severity(left) >= severity(right) ? left : right;
+}
+function severity(risk) {
+    return {
+        UNKNOWN: 0,
+        READ: 1,
+        DATA_WRITE: 2,
+        SCHEMA_WRITE: 3,
+        DANGEROUS: 4,
+    }[risk];
+}

package/dist/src/tools.d.ts

@@ -0,0 +1,9 @@
+import type { BridgeConfig } from './config.js';
+import type { NubaseClient } from './nubase-client.js';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export declare const TOOLS: ToolDefinition[];
+export declare function callTool(name: string, args: Record<string, unknown>, config: BridgeConfig, client: NubaseClient): Promise<any>;

package/dist/src/tools.js

@@ -0,0 +1,94 @@
+import { withScope } from './context.js';
+export const TOOLS = [
+    {
+        name: 'nubase_capabilities',
+        description: 'Discover Nubase backend capabilities and stable API paths.',
+        inputSchema: objectSchema({}),
+    },
+    {
+        name: 'nubase_instructions',
+        description: 'Return agent instructions for using Nubase safely.',
+        inputSchema: objectSchema({}),
+    },
+    {
+        name: 'memory_context',
+        description: 'Return compact relevant memory context for a task. Scope defaults can come from NUBASE_USER_ID, NUBASE_AGENT_ID, and NUBASE_RUN_ID.',
+        inputSchema: objectSchema({
+            task: { type: 'string' },
+            topK: { type: 'number' },
+            userId: { type: 'string' },
+            agentId: { type: 'string' },
+            runId: { type: 'string' },
+        }, ['task']),
+    },
+    {
+        name: 'memory_search',
+        description: 'Search Nubase long-term memory.',
+        inputSchema: objectSchema({
+            query: { type: 'string' },
+            topK: { type: 'number' },
+            userId: { type: 'string' },
+            agentId: { type: 'string' },
+            runId: { type: 'string' },
+        }, ['query']),
+    },
+    {
+        name: 'memory_write',
+        description: 'Write durable Nubase memory.',
+        inputSchema: objectSchema({
+            content: { type: 'string' },
+            infer: { type: 'boolean' },
+            userId: { type: 'string' },
+            agentId: { type: 'string' },
+            runId: { type: 'string' },
+        }, ['content']),
+    },
+    {
+        name: 'rest_select',
+        description: 'Call Nubase /rest/v1 for a table using a PostgREST query string, for example select=*&limit=10.',
+        inputSchema: objectSchema({
+            table: { type: 'string' },
+            query: { type: 'string' },
+        }, ['table']),
+    },
+    {
+        name: 'sql_dry_run',
+        description: 'Classify SQL risk and statement count without executing it.',
+        inputSchema: objectSchema({ sql: { type: 'string' } }, ['sql']),
+    },
+    {
+        name: 'sql_execute',
+        description: 'Execute SQL through Nubase admin API. Disabled unless NUBASE_ALLOW_SQL_EXECUTE=true.',
+        inputSchema: objectSchema({ sql: { type: 'string' } }, ['sql']),
+    },
+];
+export async function callTool(name, args, config, client) {
+    switch (name) {
+        case 'nubase_capabilities':
+            return client.capabilities();
+        case 'nubase_instructions':
+            return client.instructions();
+        case 'memory_context':
+            return client.memoryContext(withScope(config, args));
+        case 'memory_search':
+            return client.memorySearch(withScope(config, args));
+        case 'memory_write':
+            return client.memoryWrite(withScope(config, args));
+        case 'rest_select':
+            return client.restSelect(args);
+        case 'sql_dry_run':
+            return client.sqlDryRun(args);
+        case 'sql_execute':
+            return client.sqlExecute(args);
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+function objectSchema(properties, required = []) {
+    return {
+        type: 'object',
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@nubase_ai/mcp-bridge",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "nubase-mcp-bridge": "dist/src/index.js"
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test dist/test/*.test.js",
+    "prepack": "pnpm run build",
+    "pack:check": "npm_config_cache=../../.npm-cache npm pack --dry-run"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "typescript": "^5.5.4"
+  }
+}