@meowlynxsea/koi 0.1.0

package/src/services/mcp/index.ts

@@ -0,0 +1,80 @@
+/**
+ * MCP Services - Koi Agent
+ *
+ * Model Context Protocol integration for Koi Agent.
+ * Supports stdio, SSE, HTTP, and WebSocket transport types.
+ */
+
+// Types
+export * from "./types.js";
+
+// Configuration
+export {
+  setMcpConfig,
+  getMcpConfig,
+  getAllMcpConfigs,
+  getMcpConfigsByScope,
+  removeMcpConfig,
+  isMcpServerDisabled,
+  setMcpServerEnabled,
+  getMcpServerNames,
+  loadMcpConfigs,
+  loadProjectMcpConfig,
+  loadLocalMcpConfig,
+  validateMcpConfig,
+  exportMcpConfigs,
+  importMcpConfigs,
+} from "./config.js";
+
+export type {
+  McpConfigValidationResult,
+  McpConfigExport,
+} from "./config.js";
+
+// Client
+export {
+  connectToServer,
+  disconnectFromServer,
+  callMcpTool,
+  listMcpResources,
+  readMcpResource,
+  listMcpPrompts,
+  executeMcpPrompt,
+} from "./client.js";
+
+export type { ConnectResult } from "./client.js";
+
+// Connection Manager
+export {
+  initializeMcpConnections,
+  connectMcpServer,
+  disconnectMcpServer,
+  reconnectMcpServer,
+  toggleMcpServer,
+  getMcpConnections,
+  getMcpConnection,
+  getConnectedServers,
+  getAllMcpTools,
+  getAllMcpResources,
+  getMcpStatusSummary,
+  isMcpConnecting,
+  getMcpError,
+  disconnectAllMcpServers,
+  resetMcpConnectionManager,
+  type McpConnectionProgress,
+  type McpProgressCallback,
+} from "./connection-manager.js";
+
+// Stdio Transport with JSON filtering
+export { FilteredStdioClientTransport } from "./stdio-transport.js";
+
+// Commands
+export {
+  addMcpServer,
+  removeMcpServer,
+  enableMcpServer,
+  disableMcpServer,
+  refreshMcpServer,
+  getMcpServerInfo,
+  parseMcpArgs,
+} from "./mcp-commands.js";

package/src/services/mcp/mcp-commands.ts

@@ -0,0 +1,114 @@
+/**
+ * MCP Command Support
+ */
+
+import type { ScopedMcpConfig } from "./types.js";
+import { getMcpConfig, setMcpConfig, removeMcpConfig, isMcpServerDisabled, setMcpServerEnabled, validateMcpConfig } from "./config.js";
+import { connectMcpServer, disconnectMcpServer, reconnectMcpServer, getMcpConnections } from "./connection-manager.js";
+
+export async function addMcpServer(name: string, config: Partial<ScopedMcpConfig>): Promise<{ success: boolean; error?: string; warning?: string }> {
+  const validation = validateMcpConfig(name, config);
+  if (!validation.valid) {
+    return { success: false, error: validation.errors?.join(", ") ?? "Invalid configuration" };
+  }
+
+  const existing = getMcpConfig(name);
+  if (existing) {
+    return { success: false, error: `Server '${name}' already exists` };
+  }
+
+  setMcpConfig(name, config, "user");
+  const result = await connectMcpServer(name);
+  if (!result.success) {
+    return { success: true, warning: `Server added but failed to connect: ${result.error}` };
+  }
+  return { success: true };
+}
+
+export function removeMcpServer(name: string): { success: boolean; error?: string } {
+  const config = getMcpConfig(name);
+  if (!config) return { success: false, error: `Server '${name}' not found` };
+  disconnectMcpServer(name).catch(() => {});
+  removeMcpConfig(name);
+  return { success: true };
+}
+
+export function enableMcpServer(name: string): { success: boolean; error?: string } {
+  const config = getMcpConfig(name);
+  if (!config) return { success: false, error: `Server '${name}' not found` };
+  setMcpServerEnabled(name, true);
+  return { success: true };
+}
+
+export function disableMcpServer(name: string): { success: boolean; error?: string } {
+  const config = getMcpConfig(name);
+  if (!config) return { success: false, error: `Server '${name}' not found` };
+  setMcpServerEnabled(name, false);
+  disconnectMcpServer(name).catch(() => {});
+  return { success: true };
+}
+
+export async function refreshMcpServer(name: string, options?: { onProgress?: (message: string) => void }): Promise<{ success: boolean; error?: string }> {
+  const config = getMcpConfig(name);
+  if (!config) return { success: false, error: `Server '${name}' not found` };
+  options?.onProgress?.(`Reconnecting to ${name}...`);
+  const result = await reconnectMcpServer(name, { onProgress: options?.onProgress });
+  if (!result.success) return { success: false, error: result.error };
+  return { success: true };
+}
+
+export function getMcpServerInfo(name: string): {
+  name: string;
+  config?: Partial<ScopedMcpConfig>;
+  status: string;
+  toolCount?: number;
+  resourceCount?: number;
+  error?: string;
+} {
+  const config = getMcpConfig(name);
+  if (!config) return { name, status: "not_found" };
+  const connection = getMcpConnections().get(name);
+  const status = connection?.status ?? (isMcpServerDisabled(name) ? "disabled" : "disconnected");
+  const connectedConn = connection?.status === "connected" ? connection : null;
+  return {
+    name,
+    config,
+    status,
+    toolCount: connectedConn?.tools?.length,
+    resourceCount: connectedConn?.resources?.length,
+    error: connection?.status === "failed" ? (connection as { error?: string }).error : undefined,
+  };
+}
+
+export function parseMcpArgs(args: string): {
+  name?: string;
+  type?: "stdio" | "sse" | "http" | "ws";
+  command?: string;
+  url?: string;
+  args?: string[];
+} {
+  const result: { name?: string; type?: "stdio" | "sse" | "http" | "ws"; command?: string; url?: string; args?: string[] } = {};
+  const parts = args.trim().split(/\s+/);
+  let i = 0;
+  while (i < parts.length) {
+    const part = parts[i]!;
+    if (part === "--stdio" || part === "-s") { result.type = "stdio"; i++; }
+    else if (part === "--sse" || part === "-e") { result.type = "sse"; i++; }
+    else if (part === "--http" || part === "-h") { result.type = "http"; i++; }
+    else if (part === "--ws" || part === "-w") { result.type = "ws"; i++; }
+    else if (part === "--name" || part === "-n") { result.name = parts[++i]; i++; }
+    else if (part.startsWith("-")) { i++; }
+    else if (!result.name && !result.command && !result.url) {
+      if (part.includes("://")) { result.url = part; }
+      else { result.command = part; }
+      i++;
+    } else if (result.command || result.url) {
+      result.args = result.args ?? [];
+      result.args.push(part);
+      i++;
+    } else {
+      i++;
+    }
+  }
+  return result;
+}

package/src/services/mcp/stdio-transport.ts

@@ -0,0 +1,246 @@
+/**
+ * MCP Stdio Transport with JSON Filtering
+ * 
+ * Some MCP servers (like context7) output non-JSON text to stdout on startup,
+ * which would cause parsing errors. This wrapper filters out non-JSON lines.
+ */
+
+import spawn from "cross-spawn";
+import process from "node:process";
+import { getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+
+// Transport interface for FilteredStdioClientTransport
+interface Transport {
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage) => void;
+  start(): Promise<void>;
+  send(message: JSONRPCMessage): Promise<void>;
+  close(): Promise<void>;
+  readonly pid?: number | null;
+}
+
+// Inline serializeMessage to avoid internal path imports
+function serializeMessage(message: JSONRPCMessage): string {
+  return JSON.stringify(message) + "\n";
+}
+
+/**
+ * Buffers a continuous stdio stream into discrete JSON-RPC messages.
+ */
+class ReadBuffer {
+  private _buffer?: Buffer;
+
+  append(chunk: Buffer): void {
+    this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
+  }
+
+  readMessage(): { line: string; remaining: Buffer | undefined } | null {
+    if (!this._buffer) {
+      return null;
+    }
+    const index = this._buffer.indexOf("\n");
+    if (index === -1) {
+      return null;
+    }
+    const line = this._buffer.toString("utf8", 0, index).replace(/\r$/, "");
+    const remaining = this._buffer.subarray(index + 1);
+    this._buffer = remaining.length > 0 ? remaining : undefined;
+    return { line, remaining };
+  }
+
+  clear(): void {
+    this._buffer = undefined;
+  }
+}
+
+function isValidJsonRpc(line: string): boolean {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{")) {
+    return false;
+  }
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    return typeof parsed === "object" && parsed !== null && "jsonrpc" in (parsed as Record<string, unknown>);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Client transport for stdio with JSON filtering.
+ * Filters out non-JSON startup messages from MCP servers.
+ */
+export class FilteredStdioClientTransport implements Transport {
+  private _process?: ReturnType<typeof spawn>;
+  private _readBuffer: ReadBuffer;
+  private _serverParams: StdioServerParameters;
+
+  onclose?: () => void;
+  onerror?: (error: Error) => void;
+  onmessage?: (message: JSONRPCMessage) => void;
+
+  constructor(server: StdioServerParameters) {
+    this._readBuffer = new ReadBuffer();
+    this._serverParams = server;
+  }
+
+  async start(): Promise<void> {
+    if (this._process) {
+      throw new Error("StdioClientTransport already started!");
+    }
+    return new Promise((resolve, reject) => {
+      // Always pipe stderr so we can capture and suppress startup messages
+      // Only inherit stderr explicitly if user requests it
+      const stderrMode: "pipe" | "inherit" | "ignore" = 
+        this._serverParams.stderr === "inherit" ? "inherit" :
+        this._serverParams.stderr === "ignore" ? "ignore" :
+        "pipe";
+
+      this._process = spawn(this._serverParams.command, this._serverParams.args ?? [], {
+        env: {
+          ...getDefaultEnvironment(),
+          ...this._serverParams.env,
+        },
+        stdio: ["pipe", "pipe", stderrMode],
+        shell: false,
+        windowsHide: process.platform === "win32",
+        cwd: this._serverParams.cwd,
+      });
+
+      this._process.on("error", (error: Error) => {
+        reject(error);
+        this.onerror?.(error);
+      });
+
+      this._process.on("spawn", () => {
+        resolve();
+      });
+
+      this._process.on("close", (_code: number) => {
+        this._process = undefined;
+        this.onclose?.();
+      });
+
+      this._process.stdin?.on("error", (error: Error) => {
+        this.onerror?.(error);
+      });
+
+      this._process.stdout?.on("data", (chunk: Buffer) => {
+        this._readBuffer.append(chunk);
+        this.processReadBuffer();
+      });
+
+      this._process.stdout?.on("error", (error: Error) => {
+        this.onerror?.(error);
+      });
+
+      // Capture stderr but don't output it to console
+      // This filters out server startup messages like "Server v2.2.4 running on stdio"
+      if (this._process.stderr) {
+        this._process.stderr.on("data", (_chunk: Buffer) => {
+          // Silently consume stderr to prevent startup messages from appearing in TUI
+          // Only emit actual errors if needed
+        });
+        this._process.stderr.on("error", () => {
+          // Ignore stderr errors
+        });
+      }
+    });
+  }
+
+  get pid(): number | null {
+    return this._process?.pid ?? null;
+  }
+
+  private processReadBuffer(): void {
+    // Filter out non-JSON lines
+    while (true) {
+      const result = this._readBuffer.readMessage();
+      if (result === null) {
+        break;
+      }
+
+      const { line } = result;
+
+      // Skip empty lines
+      if (!line.trim()) {
+        continue;
+      }
+
+      // Skip non-JSON lines (like server startup messages)
+      if (!isValidJsonRpc(line)) {
+        continue;
+      }
+
+      try {
+        const message = JSON.parse(line) as JSONRPCMessage;
+        this.onmessage?.(message);
+      } catch {
+        // Skip invalid JSON-RPC messages
+        continue;
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this._process) {
+      const processToClose = this._process;
+      this._process = undefined;
+      const closePromise = new Promise<void>((resolve) => {
+        processToClose.once("close", () => {
+          resolve();
+        });
+      });
+
+      try {
+        processToClose.stdin?.end();
+      } catch {
+        // ignore
+      }
+
+      await Promise.race([
+        closePromise,
+        new Promise<void>((resolve) => setTimeout(resolve, 2000).unref()),
+      ]);
+
+      if (processToClose.exitCode === null) {
+        try {
+          processToClose.kill("SIGTERM");
+        } catch {
+          // ignore
+        }
+        await Promise.race([
+          closePromise,
+          new Promise<void>((resolve) => setTimeout(resolve, 2000).unref()),
+        ]);
+      }
+
+      if (processToClose.exitCode === null) {
+        try {
+          processToClose.kill("SIGKILL");
+        } catch {
+          // ignore
+        }
+      }
+    }
+    this._readBuffer.clear();
+  }
+
+  send(message: JSONRPCMessage): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!this._process?.stdin) {
+        reject(new Error("Not connected"));
+        return;
+      }
+      const json = serializeMessage(message);
+      if (this._process.stdin.write(json)) {
+        resolve();
+      } else {
+        this._process.stdin.once("drain", resolve);
+      }
+    });
+  }
+}

package/src/services/mcp/types.ts

@@ -0,0 +1,155 @@
+/**
+ * MCP Types for Koi Agent
+ */
+
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Tool, Resource, ServerCapabilities } from "@modelcontextprotocol/sdk/types.js";
+
+// Transport Types
+export const TransportSchema = ["stdio", "sse", "http", "ws"] as const;
+export type Transport = (typeof TransportSchema)[number];
+
+// Configuration Types - Simple flat structure
+export interface McpServerConfig {
+  type?: "stdio" | "sse" | "http" | "ws";
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  headers?: Record<string, string>;
+  authToken?: string;
+}
+
+// Config Scope
+export type ConfigScope = "user" | "project" | "local";
+
+export interface ScopedMcpConfig extends McpServerConfig {
+  scope: ConfigScope;
+  description?: string;
+  enabled?: boolean;
+}
+
+// Config File Format
+export interface McpJsonConfig {
+  mcpServers?: Record<string, McpServerConfig>;
+}
+
+// Connection State Types
+export type ConnectionStatus = "connected" | "failed" | "pending" | "disabled" | "disconnected";
+
+export interface ConnectedMCPServer {
+  client: Client;
+  name: string;
+  status: "connected";
+  capabilities: ServerCapabilities;
+  serverInfo?: { name: string; version: string };
+  instructions?: string;
+  config: ScopedMcpConfig;
+  tools: Tool[];
+  resources: Resource[];
+  cleanup: () => Promise<void>;
+}
+
+export interface FailedMCPServer {
+  name: string;
+  status: "failed";
+  config: ScopedMcpConfig;
+  error?: string;
+  lastAttempt?: number;
+}
+
+export interface PendingMCPServer {
+  name: string;
+  status: "pending";
+  config: ScopedMcpConfig;
+  reconnectAttempt?: number;
+  maxReconnectAttempts?: number;
+}
+
+export interface DisabledMCPServer {
+  name: string;
+  status: "disabled";
+  config: ScopedMcpConfig;
+}
+
+export interface DisconnectedMCPServer {
+  name: string;
+  status: "disconnected";
+  config: ScopedMcpConfig;
+}
+
+export type MCPServerConnection =
+  | ConnectedMCPServer
+  | FailedMCPServer
+  | PendingMCPServer
+  | DisabledMCPServer
+  | DisconnectedMCPServer;
+
+// Serialized Types
+export interface SerializedTool {
+  name: string;
+  description?: string;
+  inputSchema?: Tool["inputSchema"];
+  isMcp?: boolean;
+  serverName?: string;
+  originalToolName?: string;
+}
+
+export interface SerializedServer {
+  name: string;
+  status: ConnectionStatus;
+  capabilities?: ServerCapabilities;
+  serverInfo?: { name: string; version: string };
+  error?: string;
+  toolCount?: number;
+  resourceCount?: number;
+}
+
+export interface MCPSerializedState {
+  servers: SerializedServer[];
+  configs: Record<string, ScopedMcpConfig>;
+  tools: SerializedTool[];
+}
+
+// Resource Types
+export interface ServerResource extends Resource {
+  server: string;
+  serverName?: string;
+}
+
+// MCP Tool Call Types
+export interface McpToolCall {
+  serverName: string;
+  toolName: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface McpToolResult {
+  success: boolean;
+  content?: Array<{ type: string; text?: string; [key: string]: unknown }>;
+  error?: string;
+  isError?: boolean;
+}
+
+// Configuration Validation
+export function isStdioConfig(config: McpServerConfig): boolean {
+  if (config.type === "stdio") return true;
+  return !!config.command && !config.url;
+}
+
+export function isRemoteConfig(config: McpServerConfig): boolean {
+  return !!config.url;
+}
+
+export function validateMcpServerConfig(config: unknown): config is McpServerConfig {
+  if (!config || typeof config !== "object") return false;
+  const obj = config as Record<string, unknown>;
+  return ("command" in obj && typeof obj["command"] === "string") ||
+         ("url" in obj && typeof obj["url"] === "string");
+}
+
+export function getServerTransport(config: McpServerConfig): Transport {
+  if (config.type === "stdio") return "stdio";
+  if (config.type === "sse" || config.type === "http" || config.type === "ws") return config.type;
+  return "stdio";
+}