min-agent 0.1.0

package/src/mcp.ts

@@ -0,0 +1,300 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"
+import { tool, jsonSchema, type Tool } from "ai"
+import type { JSONSchema7 } from "@ai-sdk/provider"
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from "fs"
+import path from "path"
+import { truncateToolOutput } from "./tool-output.js"
+
+export interface McpServerConfig {
+  /** Local stdio server: command + args. Ignored when `url` is set. */
+  command?: string[]
+  /** Remote MCP endpoint (http/https). When set, connects via HTTP transport instead of stdio. */
+  url?: string
+  /**
+   * Remote transport mode.
+   * - `streamable-http`: MCP Streamable HTTP (default for new remote servers)
+   * - `sse`: legacy HTTP + SSE transport
+   * - `auto`: try streamable-http first, then fall back to sse
+   */
+  remoteTransport?: "streamable-http" | "sse" | "auto"
+  /** Shorthand: sets `Authorization: Bearer <token>` if not already present in `headers`. */
+  token?: string
+  /** Extra HTTP headers for remote transports. */
+  headers?: Record<string, string>
+  environment?: Record<string, string>
+  enabled?: boolean
+  timeout?: number
+}
+
+export interface McpConfig {
+  mcpServers: Record<string, McpServerConfig>
+}
+
+type McpClientTransport = StdioClientTransport | StreamableHTTPClientTransport | SSEClientTransport
+
+interface ConnectedServer {
+  client: Client
+  transport: McpClientTransport
+  tools: Array<{ name: string; description?: string; inputSchema: any }>
+}
+
+const DEFAULT_TIMEOUT = 30000
+
+function getMcpConfigPath(): string {
+  return path.join(process.cwd(), ".min-agent", "mcp.json")
+}
+
+let connectedServers: Record<string, ConnectedServer> = {}
+
+export interface McpCheckResult {
+  name: string
+  enabled: boolean
+  ok: boolean
+  toolCount: number
+  error?: string
+}
+
+export function loadMcpConfig(): McpConfig {
+  const configPath = getMcpConfigPath()
+  if (!existsSync(configPath)) return { mcpServers: {} }
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8"))
+  } catch {
+    return { mcpServers: {} }
+  }
+}
+
+export function saveMcpConfig(config: McpConfig) {
+  const configPath = getMcpConfigPath()
+  const dir = path.dirname(configPath)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8")
+}
+
+export function isRemoteMcpConfig(config: McpServerConfig): boolean {
+  return typeof config.url === "string" && config.url.trim().length > 0
+}
+
+function buildRemoteRequestInit(config: McpServerConfig): RequestInit | undefined {
+  const headers = new Headers(config.headers ?? {})
+  const token = config.token?.trim()
+  if (token && !headers.has("Authorization")) {
+    headers.set("Authorization", `Bearer ${token}`)
+  }
+  if ([...headers.keys()].length === 0) return undefined
+  return { headers }
+}
+
+async function openStdioMcpServer(name: string, config: McpServerConfig): Promise<ConnectedServer> {
+  const [cmd, ...args] = config.command ?? []
+  if (!cmd) {
+    throw new Error(`MCP "${name}" has empty command`)
+  }
+
+  const transport = new StdioClientTransport({
+    command: cmd,
+    args,
+    env: { ...process.env, ...(config.environment ?? {}) } as Record<string, string>,
+    stderr: "pipe",
+  })
+
+  const client = new Client({ name: "agent-demo", version: "0.0.1" })
+  await client.connect(transport)
+  const { tools } = await client.listTools()
+  return { client, transport, tools }
+}
+
+async function openRemoteMcpServer(name: string, config: McpServerConfig): Promise<ConnectedServer> {
+  const rawUrl = config.url?.trim()
+  if (!rawUrl) {
+    throw new Error(`MCP "${name}" has empty url`)
+  }
+  let baseUrl: URL
+  try {
+    baseUrl = new URL(rawUrl)
+  } catch {
+    throw new Error(`MCP "${name}" has invalid url: ${rawUrl}`)
+  }
+  if (baseUrl.protocol !== "http:" && baseUrl.protocol !== "https:") {
+    throw new Error(`MCP "${name}" url must be http or https`)
+  }
+
+  const requestInit = buildRemoteRequestInit(config)
+  const mode = config.remoteTransport ?? "auto"
+
+  const connectStreamable = async () => {
+    const client = new Client({ name: "agent-demo", version: "0.0.1" })
+    const transport = new StreamableHTTPClientTransport(baseUrl, requestInit ? { requestInit } : undefined)
+    await client.connect(transport)
+    const { tools } = await client.listTools()
+    return { client, transport, tools } as ConnectedServer
+  }
+
+  const connectSse = async () => {
+    const client = new Client({ name: "agent-demo", version: "0.0.1" })
+    const transport = new SSEClientTransport(baseUrl, requestInit ? { requestInit } : undefined)
+    await client.connect(transport)
+    const { tools } = await client.listTools()
+    return { client, transport, tools } as ConnectedServer
+  }
+
+  if (mode === "streamable-http") {
+    return await connectStreamable()
+  }
+  if (mode === "sse") {
+    return await connectSse()
+  }
+
+  // auto: prefer streamable-http, fall back to sse (older servers)
+  try {
+    return await connectStreamable()
+  } catch (firstErr: any) {
+    try {
+      return await connectSse()
+    } catch {
+      throw new Error(
+        `MCP "${name}" remote connection failed (streamable-http + sse): ${firstErr?.message ?? String(firstErr)}`,
+      )
+    }
+  }
+}
+
+async function openMcpServer(name: string, config: McpServerConfig): Promise<ConnectedServer> {
+  if (isRemoteMcpConfig(config)) {
+    return await openRemoteMcpServer(name, config)
+  }
+  return await openStdioMcpServer(name, config)
+}
+
+/** One-line summary for CLI / logs (no secrets). */
+export function formatMcpServerBinding(config: McpServerConfig): string {
+  if (isRemoteMcpConfig(config)) {
+    const mode = config.remoteTransport ?? "auto"
+    return `${config.url} [remote:${mode}]`
+  }
+  return (config.command ?? []).join(" ")
+}
+
+export async function connectMcpServer(name: string, config: McpServerConfig): Promise<ConnectedServer | null> {
+  if (config.enabled === false) return null
+
+  try {
+    const server = await openMcpServer(name, config)
+    console.log(`\x1b[90m  MCP "${name}" connected (${server.tools.length} tools)\x1b[0m`)
+    return server
+  } catch (err: any) {
+    console.error(`\x1b[31m  MCP "${name}" failed: ${err.message}\x1b[0m`)
+    return null
+  }
+}
+
+export async function checkMcpServer(name: string, config: McpServerConfig): Promise<McpCheckResult> {
+  if (config.enabled === false) {
+    return { name, enabled: false, ok: true, toolCount: 0 }
+  }
+
+  try {
+    const server = await openMcpServer(name, config)
+    const toolCount = server.tools.length
+    try {
+      await server.client.close()
+    } catch {}
+    return { name, enabled: true, ok: true, toolCount }
+  } catch (err: any) {
+    return {
+      name,
+      enabled: true,
+      ok: false,
+      toolCount: 0,
+      error: err?.message ?? String(err),
+    }
+  }
+}
+
+export async function checkAllMcpServers(): Promise<McpCheckResult[]> {
+  const config = loadMcpConfig()
+  const results: McpCheckResult[] = []
+  for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+    results.push(await checkMcpServer(name, serverConfig))
+  }
+  return results
+}
+
+export async function initMcp(): Promise<void> {
+  const config = loadMcpConfig()
+  for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+    const server = await connectMcpServer(name, serverConfig)
+    if (server) connectedServers[name] = server
+  }
+}
+
+export async function shutdownMcp(): Promise<void> {
+  for (const [name, server] of Object.entries(connectedServers)) {
+    try {
+      await server.client.close()
+    } catch {}
+  }
+  connectedServers = {}
+}
+
+export function getMcpTools(): Record<string, Tool> {
+  const tools: Record<string, Tool> = {}
+
+  for (const [serverName, server] of Object.entries(connectedServers)) {
+    for (const mcpTool of server.tools) {
+      const toolId = `${sanitize(serverName)}_${sanitize(mcpTool.name)}`
+      const schema: JSONSchema7 = {
+        ...(mcpTool.inputSchema as JSONSchema7),
+        type: "object",
+        properties: (mcpTool.inputSchema?.properties ?? {}) as JSONSchema7["properties"],
+      }
+
+      tools[toolId] = tool({
+        description: mcpTool.description ?? `MCP tool: ${mcpTool.name}`,
+        inputSchema: jsonSchema(schema),
+        execute: async (args: any) => {
+          try {
+            const result = await server.client.callTool({
+              name: mcpTool.name,
+              arguments: args,
+            })
+            if (result.isError) {
+              return truncateToolOutput(`Error: ${JSON.stringify(result.content)}`, { direction: "head" }).content
+            }
+            const content = result.content as Array<{ type: string; text?: string }>
+            const text =
+              content
+                .filter((c) => c.type === "text")
+                .map((c) => c.text ?? "")
+                .join("\n") || JSON.stringify(result.content)
+            return truncateToolOutput(text, { direction: "head" }).content
+          } catch (err: any) {
+            return truncateToolOutput(`MCP tool error: ${err.message}`, { direction: "head" }).content
+          }
+        },
+      }) as Tool
+    }
+  }
+
+  return tools
+}
+
+export function getMcpStatus(): Record<string, { connected: boolean; tools: string[] }> {
+  const status: Record<string, { connected: boolean; tools: string[] }> = {}
+  const config = loadMcpConfig()
+  for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+    const server = connectedServers[name]
+    status[name] = {
+      connected: !!server,
+      tools: server?.tools.map((t) => t.name) ?? [],
+    }
+  }
+  return status
+}
+
+function sanitize(s: string): string {
+  return s.replace(/[^a-zA-Z0-9_-]/g, "_")
+}

package/src/memory.ts

@@ -0,0 +1,164 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs"
+import path from "path"
+import { getConfigDir } from "./config.js"
+import { tool, jsonSchema, type Tool } from "ai"
+
+/**
+ * Memory system for min-agent.
+ *
+ * Memories are stored as a JSON array in ~/.min-agent/memory.json.
+ * Each memory has a content string, tags, and timestamp.
+ *
+ * The agent can:
+ * - memory_save: Save a new memory (user preference, project context, learned fact)
+ * - memory_search: Search memories by keyword
+ * - memory_list: List all memories
+ * - memory_delete: Delete a memory by index
+ *
+ * Memories are automatically injected into the system prompt so the agent
+ * "remembers" things across sessions.
+ */
+
+export interface Memory {
+  content: string
+  tags: string[]
+  created: string
+}
+
+function getMemoryFile(): string {
+  return path.join(getConfigDir(), "memory.json")
+}
+
+export function loadMemories(): Memory[] {
+  const file = getMemoryFile()
+  if (!existsSync(file)) return []
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"))
+  } catch {
+    return []
+  }
+}
+
+function saveMemories(memories: Memory[]) {
+  const file = getMemoryFile()
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify(memories, null, 2), "utf-8")
+}
+
+export function addMemory(content: string, tags: string[] = []): Memory {
+  const memories = loadMemories()
+  const memory: Memory = {
+    content,
+    tags,
+    created: new Date().toISOString(),
+  }
+  memories.push(memory)
+  saveMemories(memories)
+  return memory
+}
+
+export function deleteMemory(index: number): boolean {
+  const memories = loadMemories()
+  if (index < 0 || index >= memories.length) return false
+  memories.splice(index, 1)
+  saveMemories(memories)
+  return true
+}
+
+export function searchMemories(query: string): Array<Memory & { index: number }> {
+  const memories = loadMemories()
+  const lower = query.toLowerCase()
+  return memories
+    .map((m, i) => ({ ...m, index: i }))
+    .filter(
+      (m) =>
+        m.content.toLowerCase().includes(lower) ||
+        m.tags.some((t) => t.toLowerCase().includes(lower)),
+    )
+}
+
+/** Build a system prompt section from stored memories */
+export function getMemorySystemPrompt(): string {
+  const memories = loadMemories()
+  if (memories.length === 0) return ""
+
+  const items = memories.map((m, i) => {
+    const tags = m.tags.length > 0 ? ` [${m.tags.join(", ")}]` : ""
+    return `  ${i + 1}. ${m.content}${tags}`
+  })
+
+  return [
+    "## Memories",
+    "The following are things you have remembered from previous conversations. Use them to provide better, personalized responses.",
+    "You can save new memories with the memory_save tool when the user tells you something worth remembering (preferences, project details, conventions, etc).",
+    "",
+    ...items,
+  ].join("\n")
+}
+
+/** Create the memory tools for the agent */
+export function getMemoryTools(): Record<string, Tool> {
+  const memorySave = tool<{ content: string; tags?: string[] }, string>({
+    description:
+      "Save a memory for future conversations. Use this when the user shares preferences, project conventions, important context, or asks you to remember something. Memories persist across sessions.",
+    inputSchema: jsonSchema<{ content: string; tags?: string[] }>({
+      type: "object",
+      properties: {
+        content: { type: "string", description: "The information to remember" },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional tags for categorization (e.g. 'preference', 'project', 'convention')",
+        },
+      },
+      required: ["content"],
+    }),
+    execute: async ({ content, tags }) => {
+      const memory = addMemory(content, tags ?? [])
+      return `Saved memory: "${content}" (tags: ${memory.tags.length > 0 ? memory.tags.join(", ") : "none"})`
+    },
+  })
+
+  const memorySearch = tool<{ query: string }, string>({
+    description: "Search through saved memories by keyword. Use this to recall previously saved information.",
+    inputSchema: jsonSchema<{ query: string }>({
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search keyword or phrase" },
+      },
+      required: ["query"],
+    }),
+    execute: async ({ query }) => {
+      const results = searchMemories(query)
+      if (results.length === 0) return `No memories found matching "${query}"`
+      return results
+        .map((m) => {
+          const tags = m.tags.length > 0 ? ` [${m.tags.join(", ")}]` : ""
+          return `#${m.index + 1}: ${m.content}${tags} (${m.created.split("T")[0]})`
+        })
+        .join("\n")
+    },
+  })
+
+  const memoryDelete = tool<{ index: number }, string>({
+    description: "Delete a memory by its number. Use memory_search or memory_list first to find the index.",
+    inputSchema: jsonSchema<{ index: number }>({
+      type: "object",
+      properties: {
+        index: { type: "number", description: "The memory number to delete (1-based)" },
+      },
+      required: ["index"],
+    }),
+    execute: async ({ index }) => {
+      const success = deleteMemory(index - 1)
+      if (success) return `Memory #${index} deleted.`
+      return `Memory #${index} not found.`
+    },
+  })
+
+  return {
+    memory_save: memorySave as Tool,
+    memory_search: memorySearch as Tool,
+    memory_delete: memoryDelete as Tool,
+  }
+}

package/src/output.ts

@@ -0,0 +1,58 @@
+import type { LanguageModelUsage } from "ai"
+import { loadConfig } from "./config.js"
+
+const COLORS = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  magenta: "\x1b[35m",
+  gray: "\x1b[90m",
+}
+
+export function printHeader(modelId?: string) {
+  const config = loadConfig()
+  const model = modelId ?? config.provider?.defaultModel ?? "unknown"
+  console.log(`${COLORS.bold}🤖 min-agent${COLORS.reset} ${COLORS.dim}(${model})${COLORS.reset}`)
+}
+
+export function printDivider() {
+  console.log(`${COLORS.dim}${"─".repeat(60)}${COLORS.reset}`)
+}
+
+export function printToolCall(name: string, input: unknown) {
+  const argsStr = formatArgs(input)
+  console.log(`\n${COLORS.yellow}⚡ ${name}${COLORS.reset} ${COLORS.dim}${argsStr}${COLORS.reset}`)
+}
+
+export function printToolResult(name: string, result: unknown) {
+  const output = typeof result === "string" ? result : JSON.stringify(result, null, 2)
+  const lines = output.split("\n")
+  const maxLines = 20
+  const truncated = lines.length > maxLines
+  const preview = truncated ? lines.slice(0, maxLines).join("\n") : output
+  const display = preview.length > 500 ? preview.slice(0, 500) + "..." : preview
+  const suffix = truncated ? ` (${lines.length - maxLines} more lines)` : ""
+  console.log(`${COLORS.green}  ✓${COLORS.reset} ${COLORS.dim}${display}${suffix}${COLORS.reset}\n`)
+}
+
+export function printDone(steps: number, usage: LanguageModelUsage) {
+  const input = usage.inputTokens ?? 0
+  const output = usage.outputTokens ?? 0
+  const total = input + output
+  console.log(`${COLORS.dim}Done in ${steps} step(s) | Tokens: ${input} in / ${output} out / ${total} total${COLORS.reset}`)
+}
+
+function formatArgs(args: unknown): string {
+  if (!args || typeof args !== "object") return ""
+  const entries = Object.entries(args as Record<string, unknown>)
+  if (entries.length === 0) return ""
+  const parts = entries.map(([k, v]) => {
+    const val = typeof v === "string" ? (v.length > 60 ? v.slice(0, 60) + "..." : v) : JSON.stringify(v)
+    return `${k}=${val}`
+  })
+  return parts.join(" ")
+}

package/src/plugins.ts

@@ -0,0 +1,94 @@
+import { tool, jsonSchema, type Tool } from "ai"
+import { existsSync, readdirSync } from "fs"
+import { pathToFileURL } from "url"
+import path from "path"
+import { getConfigDir } from "./config.js"
+
+/**
+ * Plugin system: load custom tools from .min-agent/tools/*.ts or ~/.min-agent/tools/*.ts
+ *
+ * Each plugin file should export one or more tool definitions:
+ *
+ * ```ts
+ * export const myTool = {
+ *   description: "What this tool does",
+ *   parameters: { query: { type: "string", description: "..." } },
+ *   execute: async (args) => { return "result" }
+ * }
+ * ```
+ */
+
+interface PluginToolDef {
+  description: string
+  parameters: Record<string, { type: string; description?: string }>
+  execute: (args: any) => Promise<string>
+}
+
+const PLUGIN_DIRS = [
+  path.join(process.cwd(), ".min-agent", "tools"),
+  path.join(getConfigDir(), "tools"),
+]
+
+export async function loadPluginTools(): Promise<Record<string, Tool>> {
+  const tools: Record<string, Tool> = {}
+
+  for (const dir of PLUGIN_DIRS) {
+    if (!existsSync(dir)) continue
+
+    const files = readdirSync(dir).filter((f) => f.endsWith(".ts") || f.endsWith(".js") || f.endsWith(".mjs"))
+
+    for (const file of files) {
+      const filePath = path.join(dir, file)
+      const namespace = path.basename(file, path.extname(file))
+
+      try {
+        const mod = await import(pathToFileURL(filePath).href)
+
+        for (const [exportName, def] of Object.entries(mod)) {
+          if (!isPluginTool(def)) continue
+
+          const toolId = exportName === "default" ? namespace : `${namespace}_${exportName}`
+          const properties: Record<string, any> = {}
+          const required: string[] = []
+
+          for (const [key, param] of Object.entries(def.parameters)) {
+            properties[key] = { type: param.type, description: param.description }
+            required.push(key)
+          }
+
+          tools[toolId] = tool({
+            description: def.description,
+            inputSchema: jsonSchema({
+              type: "object",
+              properties,
+              required,
+            }),
+            execute: async (args: any) => {
+              try {
+                const result = await def.execute(args)
+                return typeof result === "string" ? result : JSON.stringify(result)
+              } catch (err: any) {
+                return `Plugin error: ${err.message}`
+              }
+            },
+          }) as Tool
+        }
+      } catch (err: any) {
+        console.error(`\x1b[90m  Plugin "${file}" failed to load: ${err.message}\x1b[0m`)
+      }
+    }
+  }
+
+  const count = Object.keys(tools).length
+  if (count > 0) {
+    console.log(`\x1b[90m  Plugins loaded: ${count} tool(s)\x1b[0m`)
+  }
+
+  return tools
+}
+
+function isPluginTool(value: unknown): value is PluginToolDef {
+  if (!value || typeof value !== "object") return false
+  const obj = value as any
+  return typeof obj.description === "string" && typeof obj.parameters === "object" && typeof obj.execute === "function"
+}

package/src/provider.ts

@@ -0,0 +1,50 @@
+import { createOpenAI } from "@ai-sdk/openai"
+import type { LanguageModel } from "ai"
+import { loadConfig } from "./config.js"
+
+function normalizeOllamaBaseURL(baseURL: string): string {
+  const trimmed = baseURL.replace(/\/$/, "")
+  return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`
+}
+
+export function resolveModel(modelId?: string): LanguageModel {
+  const config = loadConfig()
+  const provider = config.provider
+
+  if (!provider?.baseURL || !provider?.apiKey) {
+    throw new Error("Not configured. Run: min-agent setup")
+  }
+
+  const id = modelId ?? provider.defaultModel
+  if (!id) {
+    throw new Error("No model specified. Run: min-agent setup")
+  }
+
+  const type = provider.type ?? "openai-compatible"
+
+  switch (type) {
+    case "openai": {
+      const client = createOpenAI({ apiKey: provider.apiKey })
+      return client.chat(id) as unknown as LanguageModel
+    }
+
+    case "ollama": {
+      // Ollama exposes an OpenAI-compatible API at /v1.
+      // Accept both "...:11434" and "...:11434/v1" in user config.
+      const client = createOpenAI({
+        baseURL: normalizeOllamaBaseURL(provider.baseURL),
+        apiKey: provider.apiKey || "ollama",
+      })
+      return client.chat(id) as unknown as LanguageModel
+    }
+
+    case "openai-compatible":
+    default: {
+      const client = createOpenAI({
+        baseURL: provider.baseURL,
+        apiKey: provider.apiKey,
+      })
+      return client.chat(id) as unknown as LanguageModel
+    }
+  }
+}