@calypso-rag/calypso-mcp 1.0.23

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calypso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,227 @@
+# Calypso RAG MCP Server
+
+[![smithery badge](https://smithery.ai/badge/multimodal-rag/calypso-mcp-server)](https://smithery.ai/servers/multimodal-rag/calypso-mcp-server)
+
+This MCP server exposes the **Calypso RAG agent** to MCP clients such as Cursor and Claude Desktop. It is a thin bridge to Calypso's OpenAI-compatible API and forwards every request to the `calypso-rag-agent` model.
+
+Docs: `https://docs.calypso.ms/`
+
+## What you get
+
+- **`calypso-rag-agent`**: a single tool that sends each turn directly to the Calypso RAG agent
+
+The tool accepts a single `prompt` argument.
+
+## What this MCP does
+
+With `calypso-rag-agent` you can:
+
+- Ask grounded questions against the configured Calypso knowledge base
+- Continue a multi-turn conversation via the native `/v1/responses` conversation model
+- Reset the conversation context with `/new`
+- Use the same OpenAI-compatible Responses endpoint that serves `calypso-rag-agent`
+
+## Requirements
+
+- Node.js 18+
+- A Calypso API endpoint that exposes:
+  - `POST /v1/responses`
+- A Calypso API key (`sk-...`)
+
+## Configuration
+
+Environment variables:
+
+- `CALYPSO_API_KEY` (required)
+- `CALYPSO_API_BASE_URL` (optional, default `https://api.calypso.so/v1`)
+
+CLI flags:
+
+- `--api-key`
+- `--api-base-url`
+
+Configuration precedence:
+
+1. CLI flags / Smithery-provided command arguments
+2. Environment variables
+3. Default base URL (`https://api.calypso.so/v1`)
+
+## Run with npx
+
+```bash
+npx -y @calypso-rag/calypso-mcp --api-key "sk-..."
+```
+
+## Run with environment variables
+
+```bash
+env CALYPSO_API_KEY="sk-..." CALYPSO_API_BASE_URL="https://api.calypso.so/v1" npx -y @calypso-rag/calypso-mcp
+```
+
+## Configure in Cursor
+
+Add a new MCP server (command type) like:
+
+```bash
+npx -y @calypso-rag/calypso-mcp --api-key sk-... --api-base-url https://api.calypso.so/v1
+```
+
+## Smithery
+
+This repo includes a [`smithery.yaml`](./smithery.yaml) manifest that launches the published package with CLI flags instead of relying on a prebuilt local `dist/` directory.
+
+For local `.mcpb` publishing, Smithery capabilities are populated from a full MCP-style server card. This repo keeps that metadata in [`smithery.server-card.json`](./smithery.server-card.json) and publishes it with [`scripts/publish-smithery.mjs`](./scripts/publish-smithery.mjs), because MCPB `manifest.json` does not support the full `inputSchema` shape Smithery expects for capabilities.
+
+Smithery user config:
+
+- `calypsoApiKey` (required)
+- `calypsoApiBaseUrl` (optional, defaults to `https://api.calypso.so/v1`)
+
+The Smithery launch path is equivalent to:
+
+```bash
+npx -y @calypso-rag/calypso-mcp --api-key sk-... --api-base-url https://api.calypso.so/v1
+```
+
+Use `calypsoApiBaseUrl` only when targeting a self-hosted Calypso-compatible deployment. The cloud default does not need an override.
+
+## Publish-readiness validation
+
+Before publishing to Smithery, run:
+
+```bash
+npm run validate:smithery
+```
+
+That validation flow does two things:
+
+- builds the package
+- runs a local stdio smoke test that launches the built server and verifies that `calypso-rag-agent` is registered
+
+You can also run the smoke test directly after a build:
+
+```bash
+npm run build
+npm run smoke:stdio
+```
+
+To build the local Smithery / MCPB bundle:
+
+```bash
+npm run build:mcpb
+```
+
+That produces `server.mcpb` in the repo root. You can then publish it with Smithery:
+
+```bash
+smithery mcp publish ./server.mcpb -n multimodal-rag/calypso-mcp-server
+```
+
+To publish the bundle together with the capabilities metadata used by the Smithery UI:
+
+```bash
+SMITHERY_API_KEY=... npm run publish:smithery -- --name multimodal-rag/calypso-mcp-server
+```
+
+That command rebuilds `server.mcpb` and uploads it with the server card from `smithery.server-card.json`, so Smithery can render the `calypso-rag-agent` capability with its input schema.
+
+## Publish to npm
+
+This package is intended to be published publicly as:
+
+```bash
+@calypso-rag/calypso-mcp
+```
+
+Recommended release flow:
+
+```bash
+npm login
+npm whoami
+npm run build
+npm publish --access public
+```
+
+After publishing, clients can launch it with:
+
+```bash
+npx -y @calypso-rag/calypso-mcp
+```
+
+## Troubleshooting
+
+- **Missing API key**: provide `--api-key` or `CALYPSO_API_KEY`
+- **Wrong API host**: make sure `--api-base-url` / `CALYPSO_API_BASE_URL` ends in `/v1`
+- **Self-hosted deployment**: only override the base URL if you are not using `https://api.calypso.so/v1`
+- **Smithery launch mismatch**: use the packaged `npx -y @calypso-rag/calypso-mcp` path instead of running `node dist/index.js` from a fresh clone
+- **Missing `server.mcpb`**: run `npm run build:mcpb` before calling `smithery mcp publish`
+
+## Available tools
+
+### `calypso-rag-agent`
+Direct Calypso RAG agent access.
+
+Notes:
+- It does not auto-route to other personas or agents.
+- It uses `POST /v1/responses` instead of `POST /v1/chat/completions`.
+- First turns create a named conversation, and follow-up turns chain with `previous_response_id`.
+- Optional `fileIds` are attached as `input_file` parts and use `metadata._aicore.file_input_strategy = "rag_policy"` for retrieval-backed agent-store semantics.
+- Use `/new` as the prompt to reset the MCP conversation.
+
+### `calypso-upload-agent-file`
+Uploads a file into the agent store and returns a compatible OpenAI-style `file_id`.
+
+Notes:
+- Sends `purpose=user_data` on the upload request.
+- Sends `target_model` so the file lands in the intended agent store instead of a generic attachment path.
+- Supports either `contentBase64` for remote execution or `filePath` for local desktop usage.
+- Can optionally wait until the file is RAG-ready before returning.
+
+### `calypso-upload-knowledge-file`
+Uploads a file into the durable knowledge store and indexing pipeline.
+
+Notes:
+- Uses `POST /v1/knowledge/files`.
+- Returns knowledge-file and task metadata, not a chat attachment `file_id`.
+- Supports optional `title`, `tags`, `metadata`, and `idempotencyKey`.
+- Can optionally wait until indexing reaches a ready state before returning.
+
+## Common workflows (copy/paste)
+
+### Knowledge retrieval
+
+- **Summarize a topic**:
+  - `Summarize the knowledge base guidance for campaign approvals`
+- **Ask for a specific answer**:
+  - `What does our documentation say about indexing retries?`
+- **Compare two concepts**:
+  - `Compare file indexing with retrieval execution in the current architecture`
+- **Start a fresh thread**:
+  - `/new`
+
+### Multi-turn follow-up
+
+- **Refine a previous answer**:
+  - `Focus only on the ingestion path and ignore retrieval`
+- **Ask for sources or justification**:
+  - `Explain which documented components are involved and why`
+
+### Agent-store file flow
+
+- **Upload a file for the RAG agent**:
+  - Call `calypso-upload-agent-file` with `filename`, `mimeType`, and either `contentBase64` or `filePath`
+- **Ask over the uploaded file**:
+  - Call `calypso-rag-agent` with your `prompt` and the returned `fileIds`
+- **RAG semantics**:
+  - The MCP automatically uses `rag_policy` when `fileIds` are attached
+
+### Knowledge-store file flow
+
+- **Upload durable knowledge**:
+  - Call `calypso-upload-knowledge-file` with the file payload and optional `title`, `tags`, or `metadata`
+- **Wait for indexing**:
+  - Pass `waitForIndexing: true` if you want the tool to block until the knowledge file is indexed
+
+## Tips
+
+- **Start over**: use `/new` to reset the MCP conversation (new `conversation_id` + cleared response chain).

package/dist/config.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+export const CALYPSO_RAG_AGENT = "calypso-rag-agent";
+export const CALYPSO_UPLOAD_AGENT_FILE = "calypso-upload-agent-file";
+export const CALYPSO_UPLOAD_KNOWLEDGE_FILE = "calypso-upload-knowledge-file";
+export const DEFAULT_CALYPSO_API_BASE_URL = "https://api.calypso.so/v1";
+const optionalString = z
+    .string()
+    .trim()
+    .transform((value) => value || undefined)
+    .optional();
+export const calypsoConfigSchema = z.object({
+    apiKey: optionalString,
+    apiBaseUrl: optionalString
+        .pipe(z.string().url().endsWith("/v1").optional())
+        .default(DEFAULT_CALYPSO_API_BASE_URL),
+});
+const CLI_FLAG_ALIASES = {
+    "api-key": "apiKey",
+    "calypso-api-key": "apiKey",
+    "api-base-url": "apiBaseUrl",
+    "calypso-api-base-url": "apiBaseUrl",
+};
+function normalizeOptionalValue(value) {
+    const trimmed = (value || "").trim();
+    return trimmed || undefined;
+}
+function readFlagValue(flag, argv, index) {
+    if (flag.includes("=")) {
+        const [, rawValue = ""] = flag.split(/=(.*)/s, 2);
+        return { value: rawValue, consumedNextArg: false };
+    }
+    const nextArg = argv[index + 1];
+    if (!nextArg || nextArg.startsWith("--")) {
+        throw new Error(`Missing value for --${flag.replace(/^--/, "")}`);
+    }
+    return { value: nextArg, consumedNextArg: true };
+}
+export function parseCliOptions(argv) {
+    const options = {
+        help: false,
+        version: false,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--help" || argument === "-h") {
+            options.help = true;
+            continue;
+        }
+        if (argument === "--version" || argument === "-v") {
+            options.version = true;
+            continue;
+        }
+        if (!argument.startsWith("--")) {
+            throw new Error(`Unknown argument: ${argument}`);
+        }
+        const normalizedFlag = argument.slice(2).split("=")[0];
+        const targetOption = CLI_FLAG_ALIASES[normalizedFlag];
+        if (!targetOption) {
+            throw new Error(`Unknown argument: ${argument}`);
+        }
+        const { value, consumedNextArg } = readFlagValue(argument, argv, index);
+        options[targetOption] = normalizeOptionalValue(value);
+        if (consumedNextArg) {
+            index += 1;
+        }
+    }
+    return options;
+}
+export function resolveRuntimeConfig(options) {
+    return calypsoConfigSchema.parse({
+        apiKey: normalizeOptionalValue(options.cli.apiKey) ?? normalizeOptionalValue(options.env.CALYPSO_API_KEY),
+        apiBaseUrl: normalizeOptionalValue(options.cli.apiBaseUrl) ?? normalizeOptionalValue(options.env.CALYPSO_API_BASE_URL),
+    });
+}
+export function formatUsage(command = "calypso-mcp") {
+    return [
+        `Usage: ${command} [options]`,
+        "",
+        "Options:",
+        "  --api-key <value>           Calypso API key",
+        "  --api-base-url <value>      Calypso OpenAI-compatible base URL (must end in /v1)",
+        "  --help                      Show help",
+        "  --version                   Show version",
+        "",
+        "Environment variables:",
+        "  CALYPSO_API_KEY             Required for upload/query tool calls",
+        `  CALYPSO_API_BASE_URL        Optional, defaults to ${DEFAULT_CALYPSO_API_BASE_URL}`,
+    ].join("\n");
+}

package/dist/files.js

@@ -0,0 +1,244 @@
+import { readFile } from "fs/promises";
+import path from "path";
+const DEFAULT_MIME_TYPE = "application/octet-stream";
+const OPENAI_READY_STATE = "active";
+const KNOWLEDGE_READY_STATE = "indexed";
+const KNOWLEDGE_ERROR_STATES = new Set(["failed", "deleted"]);
+const OPENAI_POLL_MAX_ATTEMPTS = 40;
+const KNOWLEDGE_POLL_MAX_ATTEMPTS = 40;
+const POLL_INITIAL_DELAY_MS = 1000;
+const POLL_MAX_DELAY_MS = 4000;
+const POLL_BACKOFF_MULTIPLIER = 1.5;
+function buildApiUrl(config, relativePath) {
+    const normalizedPath = relativePath.startsWith("/") ? relativePath.slice(1) : relativePath;
+    return new URL(normalizedPath, `${config.apiBaseUrl}/`).toString();
+}
+function requireApiKey(config) {
+    const apiKey = String(config.apiKey || "").trim();
+    if (!apiKey) {
+        throw new Error("CALYPSO_API_KEY is required to call Calypso tools, but it is not configured.");
+    }
+    return apiKey;
+}
+async function parseResponseBody(response) {
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+        return response.json();
+    }
+    const text = await response.text();
+    if (!text) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function formatApiError(status, body) {
+    if (body && typeof body === "object") {
+        const maybeError = "error" in body && typeof body.error === "string"
+            ? body.error
+            : "message" in body && typeof body.message === "string"
+                ? body.message
+                : null;
+        if (maybeError) {
+            return `Request failed with status ${status}: ${maybeError}`;
+        }
+    }
+    if (typeof body === "string" && body.trim()) {
+        return `Request failed with status ${status}: ${body.trim()}`;
+    }
+    return `Request failed with status ${status}`;
+}
+async function requestJson(config, relativePath, init) {
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${requireApiKey(config)}`);
+    const response = await fetch(buildApiUrl(config, relativePath), {
+        ...init,
+        headers,
+    });
+    const body = await parseResponseBody(response);
+    if (!response.ok) {
+        throw new Error(formatApiError(response.status, body));
+    }
+    return body;
+}
+function stripDataUriPrefix(value) {
+    const marker = ";base64,";
+    const markerIndex = value.indexOf(marker);
+    if (markerIndex === -1) {
+        return value;
+    }
+    return value.slice(markerIndex + marker.length);
+}
+async function resolveUploadContent(input) {
+    const hasContentBase64 = typeof input.contentBase64 === "string" && input.contentBase64.trim().length > 0;
+    const hasFilePath = typeof input.filePath === "string" && input.filePath.trim().length > 0;
+    if (hasContentBase64 === hasFilePath) {
+        throw new Error("Provide exactly one of `contentBase64` or `filePath`.");
+    }
+    const filename = (input.filename || "").trim() || (hasFilePath && input.filePath ? path.basename(input.filePath) : "");
+    if (!filename) {
+        throw new Error("A filename is required.");
+    }
+    const mimeType = (input.mimeType || "").trim() || DEFAULT_MIME_TYPE;
+    if (hasFilePath) {
+        const bytes = await readFile(String(input.filePath));
+        return {
+            bytes,
+            filename,
+            mimeType,
+        };
+    }
+    const normalizedBase64 = stripDataUriPrefix(String(input.contentBase64).trim());
+    const bytes = Buffer.from(normalizedBase64, "base64");
+    if (bytes.byteLength === 0) {
+        throw new Error("The provided `contentBase64` value could not be decoded.");
+    }
+    return {
+        bytes,
+        filename,
+        mimeType,
+    };
+}
+function createMultipartFile(content) {
+    return new Blob([content.bytes], { type: content.mimeType || DEFAULT_MIME_TYPE });
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isOpenAiFileReady(file) {
+    return file.metadata?.rag_readiness?.state === OPENAI_READY_STATE || file.metadata?.rag_readiness?.is_ready === true;
+}
+function getOpenAiFileError(file) {
+    if (file.metadata?.rag_readiness?.state === "error") {
+        return String(file.metadata.rag_readiness.detail || file.metadata.rag_readiness.label || "File processing failed.");
+    }
+    if (file.status === "error") {
+        return "The uploaded file entered an error state.";
+    }
+    return null;
+}
+function extractKnowledgeStatus(result) {
+    return String(result.file.status || result.task?.status || "").trim().toLowerCase();
+}
+function isKnowledgeReady(result) {
+    return extractKnowledgeStatus(result) === KNOWLEDGE_READY_STATE;
+}
+function getKnowledgeError(result) {
+    const status = extractKnowledgeStatus(result);
+    if (!status) {
+        return null;
+    }
+    if (KNOWLEDGE_ERROR_STATES.has(status)) {
+        return `Knowledge indexing entered terminal status \`${status}\`.`;
+    }
+    return null;
+}
+export async function getOpenAiFile(config, fileId) {
+    return requestJson(config, `/files/${encodeURIComponent(fileId)}`, {
+        method: "GET",
+    });
+}
+export async function waitForOpenAiFileReady(config, fileId) {
+    let delayMs = POLL_INITIAL_DELAY_MS;
+    for (let attempt = 0; attempt < OPENAI_POLL_MAX_ATTEMPTS; attempt += 1) {
+        const file = await getOpenAiFile(config, fileId);
+        const readinessError = getOpenAiFileError(file);
+        if (readinessError) {
+            throw new Error(readinessError);
+        }
+        if (isOpenAiFileReady(file)) {
+            return file;
+        }
+        if (attempt < OPENAI_POLL_MAX_ATTEMPTS - 1) {
+            await sleep(delayMs);
+            delayMs = Math.min(POLL_MAX_DELAY_MS, Math.round(delayMs * POLL_BACKOFF_MULTIPLIER));
+        }
+    }
+    throw new Error("Timed out while waiting for the uploaded file to become RAG-ready.");
+}
+export async function uploadAgentFile(config, params) {
+    const content = await resolveUploadContent(params);
+    const form = new FormData();
+    form.set("purpose", "user_data");
+    form.set("target_model", params.targetModel);
+    form.set("file", createMultipartFile(content), content.filename);
+    const uploaded = await requestJson(config, "/files", {
+        method: "POST",
+        body: form,
+    });
+    if (params.waitForReady === false) {
+        return uploaded;
+    }
+    return waitForOpenAiFileReady(config, uploaded.id);
+}
+export async function getKnowledgeFile(config, fileId) {
+    return requestJson(config, `/knowledge/files/${encodeURIComponent(fileId)}`, {
+        method: "GET",
+    });
+}
+export async function getKnowledgeTask(config, taskId) {
+    return requestJson(config, `/knowledge/tasks/${encodeURIComponent(taskId)}`, {
+        method: "GET",
+    });
+}
+async function resolveKnowledgeResult(config, fileId, taskId) {
+    const file = await getKnowledgeFile(config, fileId);
+    const task = taskId ? await getKnowledgeTask(config, taskId) : file.task || null;
+    return { file, task };
+}
+export async function waitForKnowledgeFileIndexed(config, fileId, taskId) {
+    let delayMs = POLL_INITIAL_DELAY_MS;
+    for (let attempt = 0; attempt < KNOWLEDGE_POLL_MAX_ATTEMPTS; attempt += 1) {
+        const result = await resolveKnowledgeResult(config, fileId, taskId);
+        const readinessError = getKnowledgeError(result);
+        if (readinessError) {
+            throw new Error(readinessError);
+        }
+        if (isKnowledgeReady(result)) {
+            return result;
+        }
+        if (attempt < KNOWLEDGE_POLL_MAX_ATTEMPTS - 1) {
+            await sleep(delayMs);
+            delayMs = Math.min(POLL_MAX_DELAY_MS, Math.round(delayMs * POLL_BACKOFF_MULTIPLIER));
+        }
+    }
+    throw new Error("Timed out while waiting for the knowledge file to finish indexing.");
+}
+export async function uploadKnowledgeFile(config, params) {
+    const content = await resolveUploadContent(params);
+    const form = new FormData();
+    form.set("file", createMultipartFile(content), content.filename);
+    if (params.title?.trim()) {
+        form.set("title", params.title.trim());
+    }
+    for (const tag of params.tags || []) {
+        const trimmedTag = String(tag || "").trim();
+        if (trimmedTag) {
+            form.append("tags", trimmedTag);
+        }
+    }
+    if (params.metadata && Object.keys(params.metadata).length > 0) {
+        form.set("metadata", JSON.stringify(params.metadata));
+    }
+    const headers = new Headers();
+    if (params.idempotencyKey?.trim()) {
+        headers.set("Idempotency-Key", params.idempotencyKey.trim());
+    }
+    const file = await requestJson(config, "/knowledge/files", {
+        method: "POST",
+        headers,
+        body: form,
+    });
+    const initialResult = {
+        file,
+        task: file.task || null,
+    };
+    if (params.waitForIndexing !== true) {
+        return initialResult;
+    }
+    return waitForKnowledgeFileIndexed(config, file.id, file.task?.id || null);
+}

package/dist/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import dotenv from "dotenv";
+import { readFile } from "fs/promises";
+import path from "path";
+import { fileURLToPath } from "url";
+import { DEFAULT_CALYPSO_API_BASE_URL, formatUsage, parseCliOptions, resolveRuntimeConfig } from "./config.js";
+import { createCalypsoMcpServer } from "./server.js";
+const FALLBACK_PACKAGE_INFO = {
+    name: "@calypso-rag/calypso-mcp",
+    version: "0.0.0",
+};
+async function loadPackageInfo() {
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const packageJsonPath = path.join(__dirname, "..", "package.json");
+        const packageJsonContent = await readFile(packageJsonPath, "utf8");
+        const packageJson = JSON.parse(packageJsonContent);
+        return {
+            name: packageJson.name || FALLBACK_PACKAGE_INFO.name,
+            version: packageJson.version || FALLBACK_PACKAGE_INFO.version,
+        };
+    }
+    catch {
+        return FALLBACK_PACKAGE_INFO;
+    }
+}
+// Start the server with stdio transport
+async function main() {
+    try {
+        dotenv.config();
+        const packageInfo = await loadPackageInfo();
+        const cliOptions = parseCliOptions(process.argv.slice(2));
+        if (cliOptions.help) {
+            console.log(formatUsage(packageInfo.name));
+            process.exit(0);
+        }
+        if (cliOptions.version) {
+            console.log(packageInfo.version);
+            process.exit(0);
+        }
+        const runtimeConfig = resolveRuntimeConfig({
+            cli: cliOptions,
+            env: process.env,
+        });
+        const server = createCalypsoMcpServer({
+            config: runtimeConfig,
+            packageInfo,
+        });
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(`Error: ${error.message}`);
+            console.error(`Example: env CALYPSO_API_KEY=sk-... CALYPSO_API_BASE_URL=${DEFAULT_CALYPSO_API_BASE_URL} npx -y @calypso-rag/calypso-mcp`);
+            console.error("");
+            console.error(formatUsage());
+        }
+        process.exit(1);
+    }
+}
+main();

package/dist/server.js

@@ -0,0 +1,276 @@
+import { randomUUID } from "crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import OpenAI from "openai";
+import { z } from "zod";
+import { CALYPSO_RAG_AGENT, CALYPSO_UPLOAD_AGENT_FILE, CALYPSO_UPLOAD_KNOWLEDGE_FILE, } from "./config.js";
+import { uploadAgentFile, uploadKnowledgeFile } from "./files.js";
+async function processStreamingResponse(stream) {
+    let fullResponse = "";
+    let responseId = null;
+    for await (const event of stream) {
+        if (event.type === "response.output_text.delta" && typeof event.delta === "string") {
+            fullResponse += event.delta;
+        }
+        if (event.type === "response.output_text.done" && !fullResponse && typeof event.text === "string") {
+            fullResponse = event.text;
+        }
+        if (event.type === "response.completed" && typeof event.response?.id === "string") {
+            responseId = event.response.id;
+        }
+    }
+    return { text: fullResponse, responseId };
+}
+function formatJson(value) {
+    return JSON.stringify(value, null, 2);
+}
+function normalizeFileIds(fileIds) {
+    const normalized = (fileIds || [])
+        .map((fileId) => String(fileId || "").trim())
+        .filter(Boolean);
+    return normalized.length > 0 ? normalized : undefined;
+}
+function buildResponsesMetadata(options) {
+    const metadata = {
+        tool: "mcp",
+        agent: CALYPSO_RAG_AGENT,
+        conversation_id: options.conversationId,
+    };
+    if (options.fileIds && options.fileIds.length > 0) {
+        metadata._aicore = {
+            file_input_strategy: "rag_policy",
+        };
+    }
+    return metadata;
+}
+function requireApiKey(config) {
+    const apiKey = String(config.apiKey || "").trim();
+    if (!apiKey) {
+        throw new Error("CALYPSO_API_KEY is required to call Calypso tools, but it is not configured.");
+    }
+    return apiKey;
+}
+export function createCalypsoMcpServer(options) {
+    const { config, packageInfo } = options;
+    let calypsoClient = null;
+    function getCalypsoClient() {
+        if (!calypsoClient) {
+            calypsoClient = new OpenAI({
+                apiKey: requireApiKey(config),
+                baseURL: config.apiBaseUrl,
+                defaultHeaders: {
+                    "User-Agent": `${packageInfo.name}/${packageInfo.version} (Node.js/${process.versions.node})`,
+                },
+            });
+        }
+        return calypsoClient;
+    }
+    const server = new McpServer({
+        name: packageInfo.name,
+        version: packageInfo.version,
+    });
+    // MCP session state is intentionally per-process. The backend maintains the
+    // real conversation thread through previous_response_id chaining.
+    let conversationId = `conv_${randomUUID().replace(/-/g, "")}`;
+    let previousResponseId = null;
+    server.tool(CALYPSO_UPLOAD_AGENT_FILE, [
+        "[CALYPSO UPLOAD AGENT FILE]",
+        "Uploads a file into the agent store for retrieval-backed RAG use.",
+        "",
+        "Use this when you want a compatible `file_id` that can be attached to `calypso-rag-agent`.",
+        "The MCP sends `purpose=user_data`, targets the selected RAG agent with `target_model`,",
+        "and can optionally wait until the file is RAG-ready before returning.",
+    ].join("\n"), {
+        filename: z.string().describe("Display filename for the uploaded file."),
+        mimeType: z.string().describe("Content type for the uploaded file."),
+        contentBase64: z.string().optional().describe("Base64-encoded file content. Use this for Smithery or remote execution."),
+        filePath: z.string().optional().describe("Local file path to read from disk when the MCP process can access the file."),
+        targetModel: z.string().optional().describe("Optional RAG agent id. Defaults to `calypso-rag-agent`."),
+        waitForReady: z.boolean().optional().describe("If true, wait until the uploaded file is RAG-ready before returning."),
+    }, async ({ filename, mimeType, contentBase64, filePath, targetModel, waitForReady, }) => {
+        try {
+            const uploaded = await uploadAgentFile(config, {
+                filename,
+                mimeType,
+                contentBase64,
+                filePath,
+                targetModel: String(targetModel || "").trim() || CALYPSO_RAG_AGENT,
+                waitForReady,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatJson(uploaded),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            console.error(`Error calling ${CALYPSO_UPLOAD_AGENT_FILE}:`, error);
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: Failed to upload file into the agent store. ${error}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.tool(CALYPSO_UPLOAD_KNOWLEDGE_FILE, [
+        "[CALYPSO UPLOAD KNOWLEDGE FILE]",
+        "Uploads a file into the durable knowledge store and indexing pipeline.",
+        "",
+        "Use this when you want a file indexed into the broader knowledge corpus instead of",
+        "attached directly to a single RAG chat turn. This tool returns knowledge-file and task metadata.",
+    ].join("\n"), {
+        filename: z.string().describe("Display filename for the uploaded knowledge file."),
+        mimeType: z.string().describe("Content type for the uploaded knowledge file."),
+        contentBase64: z.string().optional().describe("Base64-encoded file content. Use this for Smithery or remote execution."),
+        filePath: z.string().optional().describe("Local file path to read from disk when the MCP process can access the file."),
+        title: z.string().optional().describe("Optional human-readable title stored with the knowledge file."),
+        tags: z.array(z.string()).optional().describe("Optional tags for knowledge-store organization."),
+        metadata: z.record(z.unknown()).optional().describe("Optional metadata object serialized onto the upload request."),
+        idempotencyKey: z.string().optional().describe("Optional idempotency key for durable upload retries."),
+        waitForIndexing: z.boolean().optional().describe("If true, wait until indexing reaches a terminal ready state before returning."),
+    }, async ({ filename, mimeType, contentBase64, filePath, title, tags, metadata, idempotencyKey, waitForIndexing, }) => {
+        try {
+            const result = await uploadKnowledgeFile(config, {
+                filename,
+                mimeType,
+                contentBase64,
+                filePath,
+                title,
+                tags,
+                metadata,
+                idempotencyKey,
+                waitForIndexing,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatJson(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            console.error(`Error calling ${CALYPSO_UPLOAD_KNOWLEDGE_FILE}:`, error);
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: Failed to upload file into the knowledge store. ${error}`,
+                    },
+                ],
+            };
+        }
+    });
+    server.tool(CALYPSO_RAG_AGENT, [
+        "[CALYPSO RAG AGENT]",
+        "Sends each prompt directly to the Calypso RAG agent using the full conversation context.",
+        "",
+        "Use this when you want Calypso knowledge retrieval and grounded answers from the RAG backend.",
+        "Typical requests:",
+        '- "Summarize the key points from our onboarding documentation"',
+        '- "What does the knowledge base say about campaign approval rules?"',
+        '- "Compare the documented indexing flow with the retrieval flow"',
+        '- "Answer using the uploaded file ids: [\\"file_123\\"]"',
+        "",
+        "Responses API behavior:",
+        "- First turns start a named Calypso conversation via `/v1/responses`.",
+        "- Follow-up turns chain with `previous_response_id` so the backend owns conversation state.",
+        "- When `fileIds` are provided, the MCP uses `rag_policy` retrieval semantics instead of inline attachment stuffing.",
+        "",
+        "MCP session behavior:",
+        "- This tool maintains a stable conversation id in the background for multi-turn retrieval context.",
+        "- Use `/new` to start a fresh conversation and clear the current context window.",
+        "",
+        "Quick commands (examples):",
+        '- "Summarize the latest indexed knowledge about WhatsApp templates"',
+        '- "Find the source of truth for campaign approval behavior"',
+        '- "Start a new topic" (or use `/new`)',
+    ].join("\n"), {
+        prompt: z.string().describe("Your request. Include context, constraints, and desired output."),
+        fileIds: z.array(z.string()).optional().describe("Optional uploaded agent-store `file_id` values to attach with `rag_policy` retrieval semantics."),
+    }, async ({ prompt, fileIds }) => {
+        try {
+            const userText = (prompt || "").trim();
+            const normalizedFileIds = normalizeFileIds(fileIds);
+            if (userText === "/new") {
+                conversationId = `conv_${randomUUID().replace(/-/g, "")}`;
+                previousResponseId = null;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Started a new Calypso RAG conversation. You can continue with your next request.",
+                        },
+                    ],
+                };
+            }
+            const request = {
+                model: CALYPSO_RAG_AGENT,
+                input: [
+                    {
+                        role: "user",
+                        content: [
+                            {
+                                type: "input_text",
+                                text: userText,
+                            },
+                            ...(normalizedFileIds || []).map((fileId) => ({
+                                type: "input_file",
+                                file_id: fileId,
+                            })),
+                        ],
+                    },
+                ],
+                stream: true,
+                store: true,
+                metadata: buildResponsesMetadata({
+                    conversationId,
+                    fileIds: normalizedFileIds,
+                }),
+            };
+            if (previousResponseId) {
+                request.previous_response_id = previousResponseId;
+            }
+            else {
+                request.conversation = { id: conversationId };
+            }
+            // Calypso/AIcore accepts Responses fields that this SDK version does not
+            // type yet (`conversation` and `previous_response_id`), so we narrow the
+            // cast to the API boundary.
+            const response = await getCalypsoClient().responses.create(request);
+            const result = await processStreamingResponse(response);
+            if (result.responseId) {
+                previousResponseId = result.responseId;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: result.text,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            console.error(`Error calling ${CALYPSO_RAG_AGENT}:`, error);
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: Failed to process ${CALYPSO_RAG_AGENT} query. ${error}`,
+                    },
+                ],
+            };
+        }
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@calypso-rag/calypso-mcp",
+  "version": "1.0.23",
+  "description": "MCP server for Calypso (AIcore) agents via OpenAI-compatible API.",
+  "main": "dist/index.js",
+  "homepage": "https://github.com/calypso-so/calypso-mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/calypso-so/calypso-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/calypso-so/calypso-mcp-server/issues"
+  },
+  "type": "module",
+  "bin": {
+    "calypso-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
+    "typecheck": "tsc --noEmit",
+    "validate:mcpb": "mcpb validate manifest.json",
+    "build:mcpb": "npm run build && npm run validate:mcpb && mcpb pack . server.mcpb",
+    "smoke:stdio": "node \"scripts/smoke-stdio.mjs\"",
+    "validate:smithery": "npm run build && npm run smoke:stdio && npm run validate:mcpb",
+    "publish:smithery": "npm run build:mcpb && node \"scripts/publish-smithery.mjs\"",
+    "test": "echo \"No tests specified\"",
+    "start": "node dist/index.js",
+    "lint": "echo \"No linting configured\"",
+    "format": "echo \"No formatting configured\"",
+    "prepare": "npm run build",
+    "release": "npm run build && npm publish"
+  },
+  "keywords": [
+    "mcp",
+    "calypso",
+    "aicore",
+    "smithery",
+    "rag",
+    "responses-api",
+    "agents",
+    "openai-compatible"
+  ],
+  "author": "Calypso",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.3.1",
+    "openai": "^4.20.1",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "@smithery/api": "^0.66.0",
+    "@types/node": "^20.10.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}