@syndicai/stack-mcp 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# `@syndicai/stack-mcp`
+
+Local stdio MCP server for SyndicAI Stack. Agents (OpenCode, Cursor, etc.) talk to this process; it calls satellite Memory REST with your API key. Prefer `path` for PDF/image ingest so file bytes never enter the model context.
+
+## Configure
+
+```bash
+export SYNDICAI_BASE_URL=https://chat.syndicai.dev/<slug>/v1
+export SYNDICAI_API_KEY=sk-...
+```
+
+## OpenCode
+
+```json
+{
+  "mcp": {
+    "syndicai-stack": {
+      "type": "local",
+      "command": ["npx", "-y", "@syndicai/stack-mcp"],
+      "enabled": true,
+      "environment": {
+        "SYNDICAI_BASE_URL": "https://chat.syndicai.dev/<slug>/v1",
+        "SYNDICAI_API_KEY": "sk-..."
+      }
+    }
+  }
+}
+```
+
+Monorepo / unpublished:
+
+```json
+"command": ["pnpm", "exec", "tsx", "apps/stack-mcp/src/main.ts"]
+```
+
+(run from the syndicai workspace root, or set absolute paths)
+
+## Tools
+
+| Tool                   | Purpose                                              |
+| ---------------------- | ---------------------------------------------------- |
+| `memory_search`        | Hybrid retrieve                                      |
+| `memory_ingest`        | Create/resume ingest (`path` preferred for binaries) |
+| `memory_ingest_status` | Poll job                                             |
+
+## Dev
+
+```bash
+pnpm nx test stack-mcp --tui=false
+pnpm nx run stack-mcp:typecheck --tui=false
+pnpm nx run stack-mcp:build --tui=false
+```
+
+Build output: `dist/apps/stack-mcp/` (workspace root), including copied `package.json` + `README.md`.
+
+## Publish
+
+```bash
+pnpm nx run stack-mcp:build --tui=false
+cd dist/apps/stack-mcp
+npm publish
+```
+
+Do **not** publish from `apps/stack-mcp` — compiled JS lives under workspace `dist/`.

package/config.js

@@ -0,0 +1,21 @@
+export class StackMcpConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'StackMcpConfigError';
+    }
+}
+/**
+ * Load config from env. `SYNDICAI_BASE_URL` is the OpenAI-style base ending at `/v1`
+ * (e.g. `https://chat.syndicai.dev/mem-test/v1`).
+ */
+export function loadStackMcpConfig(env = process.env) {
+    const baseUrl = env['SYNDICAI_BASE_URL']?.trim().replace(/\/$/, '') ?? '';
+    const apiKey = env['SYNDICAI_API_KEY']?.trim() ?? '';
+    if (!baseUrl) {
+        throw new StackMcpConfigError('SYNDICAI_BASE_URL is required (e.g. https://chat.syndicai.dev/<slug>/v1)');
+    }
+    if (!apiKey) {
+        throw new StackMcpConfigError('SYNDICAI_API_KEY is required');
+    }
+    return { baseUrl, apiKey };
+}

package/create-server.js

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { createMemoryClient } from './memory-client.js';
+import { registerStackMcpTools } from './tools.js';
+export function createStackMcpServer(config) {
+    const server = new McpServer({
+        name: 'syndicai-stack',
+        version: '0.1.0',
+    });
+    const client = createMemoryClient(config);
+    registerStackMcpTools(server, client);
+    return server;
+}

package/ingest-source.js

@@ -0,0 +1,92 @@
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+const TEXT_CONTENT_TYPES = new Set([
+    'text/plain',
+    'text/markdown',
+    'text/x-markdown',
+    'application/json',
+    'text/csv',
+]);
+/**
+ * Build the Memory REST ingest JSON body. When `path` is set, reads the file
+ * locally so the LLM never needs to supply bytes.
+ */
+export async function buildIngestBody(args) {
+    if (!args.sourceKey?.trim() || !args.contentType?.trim()) {
+        throw new Error('sourceKey and contentType are required');
+    }
+    const base = {
+        sourceKey: args.sourceKey.trim(),
+        contentType: args.contentType.trim(),
+        uri: args.uri,
+        collectionId: args.collectionId,
+        path: args.path,
+    };
+    if (args.path?.trim()) {
+        const filePath = args.path.trim();
+        const buf = await readFile(filePath);
+        const contentType = base.contentType || guessContentType(filePath);
+        if (isTextContentType(contentType)) {
+            return {
+                ...base,
+                contentType,
+                text: buf.toString('utf8'),
+                path: filePath,
+            };
+        }
+        return {
+            ...base,
+            contentType,
+            binaryBase64: buf.toString('base64'),
+            path: filePath,
+        };
+    }
+    if (args.text !== undefined || args.binaryBase64 !== undefined) {
+        return {
+            ...base,
+            text: args.text,
+            binaryBase64: args.binaryBase64,
+        };
+    }
+    throw new Error('Provide path, text, or binaryBase64 for memory_ingest');
+}
+function isTextContentType(contentType) {
+    const mime = (contentType.toLowerCase().split(';')[0] ?? contentType)
+        .trim()
+        .toLowerCase();
+    if (TEXT_CONTENT_TYPES.has(mime))
+        return true;
+    if (mime.startsWith('text/'))
+        return true;
+    if (mime.includes('typescript') || mime.includes('javascript'))
+        return true;
+    return false;
+}
+function guessContentType(filePath) {
+    switch (extname(filePath).toLowerCase()) {
+        case '.pdf':
+            return 'application/pdf';
+        case '.png':
+            return 'image/png';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.webp':
+            return 'image/webp';
+        case '.gif':
+            return 'image/gif';
+        case '.md':
+        case '.markdown':
+            return 'text/markdown';
+        case '.json':
+            return 'application/json';
+        case '.ts':
+        case '.tsx':
+            return 'text/x-typescript';
+        case '.js':
+        case '.jsx':
+            return 'text/javascript';
+        default:
+            return 'application/octet-stream';
+    }
+}

package/main.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadStackMcpConfig, StackMcpConfigError } from './config.js';
+import { createStackMcpServer } from './create-server.js';
+async function main() {
+    let config;
+    try {
+        config = loadStackMcpConfig();
+    }
+    catch (err) {
+        const message = err instanceof StackMcpConfigError
+            ? err.message
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        console.error(`@syndicai/stack-mcp: ${message}`);
+        process.exit(1);
+    }
+    const server = createStackMcpServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+void main().catch((err) => {
+    console.error('@syndicai/stack-mcp failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/memory-client.js

@@ -0,0 +1,69 @@
+export class MemoryHttpError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'MemoryHttpError';
+    }
+}
+export function createMemoryClient(config) {
+    const headers = {
+        Authorization: `Bearer ${config.apiKey}`,
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+    };
+    async function request(method, path, body) {
+        const url = `${config.baseUrl}${path}`;
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let parsed;
+        if (!text) {
+            parsed = null;
+        }
+        else {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok) {
+            const message = extractErrorMessage(parsed) ?? `HTTP ${res.status}`;
+            throw new MemoryHttpError(message, res.status, parsed);
+        }
+        return parsed;
+    }
+    return {
+        retrieve(params) {
+            return request('POST', '/memory/retrieve', params);
+        },
+        ingest(body) {
+            return request('POST', '/memory/ingest', body);
+        },
+        getIngest(jobId) {
+            return request('GET', `/memory/ingest/${encodeURIComponent(jobId)}`);
+        },
+    };
+}
+function extractErrorMessage(body) {
+    if (!body || typeof body !== 'object') {
+        return typeof body === 'string' && body.trim() ? body : null;
+    }
+    const record = body;
+    if (typeof record['message'] === 'string')
+        return record['message'];
+    const err = record['error'];
+    if (err && typeof err === 'object') {
+        const msg = err['message'];
+        if (typeof msg === 'string')
+            return msg;
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@syndicai/stack-mcp",
+  "version": "0.1.0",
+  "description": "Local stdio MCP server for SyndicAI Stack (Memory and future tools)",
+  "type": "module",
+  "bin": {
+    "syndicai-stack-mcp": "./main.js"
+  },
+  "files": [
+    "*.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^4.3.6"
+  }
+}

package/tools.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { buildIngestBody } from './ingest-source.js';
+import { MemoryHttpError } from './memory-client.js';
+export const MEMORY_MCP_TOOL_NAMES = [
+    'memory_search',
+    'memory_ingest',
+    'memory_ingest_status',
+];
+function textResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function toolErrorResult(err) {
+    let message = err instanceof Error ? err.message : String(err);
+    if (err instanceof MemoryHttpError && err.body) {
+        const extracted = extractNestedMessage(err.body);
+        if (extracted)
+            message = extracted;
+    }
+    return {
+        isError: true,
+        content: [{ type: 'text', text: message }],
+    };
+}
+function extractNestedMessage(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const record = body;
+    if (typeof record['message'] === 'string')
+        return record['message'];
+    return null;
+}
+export async function runMemorySearch(client, args) {
+    try {
+        const data = await client.retrieve(args);
+        return textResult(data);
+    }
+    catch (err) {
+        return toolErrorResult(err);
+    }
+}
+export async function runMemoryIngest(client, args) {
+    try {
+        const body = await buildIngestBody(args);
+        const data = await client.ingest(body);
+        return textResult(data);
+    }
+    catch (err) {
+        return toolErrorResult(err);
+    }
+}
+export async function runMemoryIngestStatus(client, args) {
+    try {
+        if (!args.jobId?.trim()) {
+            return toolErrorResult(new Error('jobId is required'));
+        }
+        const data = await client.getIngest(args.jobId.trim());
+        return textResult(data);
+    }
+    catch (err) {
+        return toolErrorResult(err);
+    }
+}
+/** Register Memory tools. Future Stack tools can be added here. */
+export function registerStackMcpTools(server, client) {
+    server.registerTool('memory_search', {
+        title: 'Search Memory',
+        description: 'Hybrid search over the squad Memory corpus (vector + lexical). Returns ranked chunk hits with content and scores.',
+        inputSchema: {
+            query: z.string().describe('Natural-language search query'),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Maximum number of hits to return'),
+            collectionId: z
+                .string()
+                .optional()
+                .describe('Optional collection filter; omit to search all'),
+        },
+    }, async (args) => runMemorySearch(client, args));
+    server.registerTool('memory_ingest', {
+        title: 'Ingest into Memory',
+        description: 'Start (or resume) a Memory ingest job. Prefer local `path` for PDFs/images so bytes stay out of the model context; ' +
+            'the MCP process reads the file and POSTs JSON (text or binaryBase64) to Memory REST. ' +
+            'If status is "paused", poll memory_ingest_status — do not re-ingest the same sourceKey while open.',
+        inputSchema: {
+            sourceKey: z
+                .string()
+                .describe('Stable source identity (e.g. repo path or doc id)'),
+            contentType: z
+                .string()
+                .describe('MIME type (e.g. text/plain, application/pdf, image/png). Used with path or inline payload.'),
+            path: z
+                .string()
+                .optional()
+                .describe('Absolute or workspace-relative filesystem path; preferred for PDF/image ingest'),
+            text: z.string().optional().describe('Plain text / source content'),
+            binaryBase64: z
+                .string()
+                .optional()
+                .describe('Base64 binary (small fixtures only; prefer path for real PDFs/images)'),
+            uri: z.string().optional().describe('Optional source URI metadata'),
+            collectionId: z.string().optional().describe('Optional collection id'),
+        },
+    }, async (args) => runMemoryIngest(client, args));
+    server.registerTool('memory_ingest_status', {
+        title: 'Ingest job status',
+        description: 'Fetch status and checkpoint for a Memory ingest job. When paused, wait and poll again.',
+        inputSchema: {
+            jobId: z.string().describe('Ingest job id from memory_ingest'),
+        },
+    }, async (args) => runMemoryIngestStatus(client, args));
+}