toolnexus 0.1.0

package/src/mcp.ts

@@ -0,0 +1,210 @@
+/**
+ * Dynamic MCP source. Mirrors opencode's mcp/index.ts + mcp/catalog.ts, but
+ * standalone (no Effect): connect to every configured server, list tools, and
+ * convert each into a uniform Tool.
+ */
+import { readFileSync } from "node:fs"
+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 type { Tool as McpToolDef } from "@modelcontextprotocol/sdk/types.js"
+import { type JSONSchema, type Tool, type ToolContext, type ToolResult, type McpStatus, sanitize } from "./types.js"
+
+const DEFAULT_TIMEOUT = 30_000
+const MAX_LIST_PAGES = 1_000
+
+export interface LocalServer {
+  type?: "local"
+  command: string[]
+  environment?: Record<string, string>
+  env?: Record<string, string>
+  cwd?: string
+  enabled?: boolean
+  disabled?: boolean
+  timeout?: number
+}
+
+export interface RemoteServer {
+  type?: "remote"
+  url: string
+  headers?: Record<string, string>
+  enabled?: boolean
+  disabled?: boolean
+  timeout?: number
+}
+
+export type ServerConfig = LocalServer | RemoteServer
+export type McpConfig = Record<string, ServerConfig>
+
+function isRemote(cfg: ServerConfig): cfg is RemoteServer {
+  if (cfg.type === "remote") return true
+  if (cfg.type === "local") return false
+  return "url" in cfg && typeof (cfg as RemoteServer).url === "string"
+}
+
+function isEnabled(cfg: ServerConfig): boolean {
+  if (cfg.disabled === true) return false
+  if (cfg.enabled === false) return false
+  return true
+}
+
+/** Accept a path, a raw object, or an object wrapped under mcpServers/servers/mcp. */
+export function parseMcpConfig(input: string | object): McpConfig {
+  const raw: any = typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input
+  const servers = raw.mcpServers ?? raw.servers ?? raw.mcp ?? raw
+  return servers as McpConfig
+}
+
+/**
+ * Expand ${ENV_VAR} in header values from process.env so tokens live in the
+ * environment, not the committed config. Values are never logged.
+ */
+export function expandEnvHeaders(headers?: Record<string, string>): Record<string, string> | undefined {
+  if (!headers) return undefined
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(headers)) {
+    out[k] = v.replace(/\$\{([A-Za-z0-9_]+)\}/g, (_, name) => process.env[name] ?? "")
+  }
+  return out
+}
+
+function formatToolErrorContent(content: unknown): string {
+  if (!Array.isArray(content)) return "MCP tool returned an error"
+  return (
+    content
+      .flatMap((item) => (isTextContent(item) ? [item.text] : []))
+      .filter((text) => text.trim())
+      .join("\n\n") || "MCP tool returned an error"
+  )
+}
+
+function isTextContent(value: unknown): value is { type: "text"; text: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as any).type === "text" &&
+    typeof (value as any).text === "string"
+  )
+}
+
+function joinTextContent(content: unknown): string {
+  if (!Array.isArray(content)) return ""
+  return content
+    .flatMap((item) => (isTextContent(item) ? [item.text] : []))
+    .join("\n")
+}
+
+async function paginateTools(client: Client, timeout: number): Promise<McpToolDef[]> {
+  const result: McpToolDef[] = []
+  const cursors = new Set<string>()
+  let cursor: string | undefined
+  for (let page = 0; page < MAX_LIST_PAGES; page++) {
+    const res = await client.listTools(cursor === undefined ? undefined : { cursor }, { timeout })
+    result.push(...res.tools)
+    if (res.nextCursor === undefined) return result
+    if (cursors.has(res.nextCursor)) throw new Error(`MCP list returned duplicate cursor: ${res.nextCursor}`)
+    cursors.add(res.nextCursor)
+    cursor = res.nextCursor
+  }
+  throw new Error(`MCP list exceeded ${MAX_LIST_PAGES} pages`)
+}
+
+function convertTool(server: string, def: McpToolDef, client: Client, timeout: number): Tool {
+  const inputSchema: JSONSchema = {
+    ...(def.inputSchema as object),
+    type: "object",
+    properties: (def.inputSchema?.properties ?? {}) as Record<string, unknown>,
+    additionalProperties: false,
+  }
+  return {
+    name: sanitize(server) + "_" + sanitize(def.name),
+    description: def.description ?? "",
+    inputSchema,
+    source: "mcp",
+    async execute(args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult> {
+      try {
+        const result: any = await client.callTool(
+          { name: def.name, arguments: args ?? {} },
+          undefined,
+          { resetTimeoutOnProgress: true, signal: ctx?.signal, timeout: ctx?.timeout ?? timeout },
+        )
+        if (result.isError) {
+          return { output: formatToolErrorContent(result.content), isError: true, metadata: { server } }
+        }
+        if (result.structuredContent !== undefined && result.structuredContent !== null) {
+          return { output: JSON.stringify(result.structuredContent), isError: false, metadata: { server } }
+        }
+        return { output: joinTextContent(result.content), isError: false, metadata: { server } }
+      } catch (e) {
+        return { output: e instanceof Error ? e.message : String(e), isError: true, metadata: { server } }
+      }
+    },
+  }
+}
+
+export interface McpSource {
+  tools: Tool[]
+  status: Record<string, McpStatus>
+  close(): Promise<void>
+}
+
+/** Connect to every enabled server, list + convert tools. Failures are isolated. */
+export async function loadMcp(input: string | object): Promise<McpSource> {
+  const config = parseMcpConfig(input)
+  const tools: Tool[] = []
+  const status: Record<string, McpStatus> = {}
+  const clients: Client[] = []
+
+  await Promise.all(
+    Object.entries(config).map(async ([name, cfg]) => {
+      if (!isEnabled(cfg)) {
+        status[name] = "disabled"
+        return
+      }
+      const timeout = cfg.timeout ?? DEFAULT_TIMEOUT
+      const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: {} })
+      try {
+        if (isRemote(cfg)) {
+          const url = new URL(cfg.url)
+          const expanded = expandEnvHeaders(cfg.headers)
+          const requestInit = expanded ? { headers: expanded } : undefined
+          try {
+            await client.connect(new StreamableHTTPClientTransport(url, { requestInit }))
+          } catch {
+            await client.connect(new SSEClientTransport(url, { requestInit }))
+          }
+        } else {
+          const local = cfg as LocalServer
+          const [cmd, ...args] = local.command
+          await client.connect(
+            new StdioClientTransport({
+              command: cmd,
+              args,
+              cwd: local.cwd,
+              env: { ...(process.env as Record<string, string>), ...(local.environment ?? local.env ?? {}) },
+              stderr: "pipe",
+            }),
+          )
+        }
+        const defs = await paginateTools(client, timeout)
+        for (const def of defs) tools.push(convertTool(name, def, client, timeout))
+        clients.push(client)
+        status[name] = "connected"
+      } catch (e) {
+        status[name] = "failed"
+        await client.close().catch(() => {})
+        // one bad server never breaks the toolkit
+        console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`)
+      }
+    }),
+  )
+
+  return {
+    tools,
+    status,
+    async close() {
+      await Promise.all(clients.map((c) => c.close().catch(() => {})))
+    },
+  }
+}

package/src/native.ts

@@ -0,0 +1,72 @@
+/**
+ * Native / annotation tools — turn a plain function into a uniform Tool.
+ * See ../../SPEC.md §6.
+ */
+import type { JSONSchema, Tool, ToolContext, ToolResult } from "./types.js"
+
+export interface DefineToolOptions {
+  name: string
+  description: string
+  inputSchema?: JSONSchema
+  source?: Tool["source"]
+  /** Return a string (wrapped as output) or a full ToolResult. */
+  run: (args: Record<string, unknown>, ctx?: ToolContext) => unknown | Promise<unknown>
+}
+
+const EMPTY_SCHEMA: JSONSchema = { type: "object", properties: {}, additionalProperties: false }
+
+/** Wrap a function as a Tool. The run() return value becomes the tool output. */
+export function defineTool(opts: DefineToolOptions): Tool {
+  return {
+    name: opts.name,
+    description: opts.description,
+    inputSchema: opts.inputSchema ?? EMPTY_SCHEMA,
+    source: opts.source ?? "native",
+    async execute(args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult> {
+      try {
+        const out = await opts.run(args ?? {}, ctx)
+        if (out && typeof out === "object" && "output" in (out as object) && "isError" in (out as object)) {
+          return out as ToolResult
+        }
+        return { output: typeof out === "string" ? out : JSON.stringify(out), isError: false }
+      } catch (e) {
+        return { output: e instanceof Error ? e.message : String(e), isError: true }
+      }
+    },
+  }
+}
+
+/**
+ * Optional decorator sugar: `@tool("description", { name, inputSchema })`.
+ * Decorated methods/functions are collected; read them with `collectTools(obj)`.
+ */
+const REGISTRY = new WeakMap<object, Tool[]>()
+
+export function tool(description: string, opts?: { name?: string; inputSchema?: JSONSchema }) {
+  return function (value: any, context: any) {
+    const fn = typeof value === "function" ? value : undefined
+    if (!fn) return value
+    const name = opts?.name ?? (context?.name ? String(context.name) : fn.name)
+    const t = defineTool({ name, description, inputSchema: opts?.inputSchema, run: (args, ctx) => fn(args, ctx) })
+    if (context?.addInitializer) {
+      context.addInitializer(function (this: object) {
+        const list = REGISTRY.get(this) ?? []
+        list.push(t)
+        REGISTRY.set(this, list)
+      })
+    }
+    ;(fn as any).__tool = t
+    return value
+  }
+}
+
+/** Gather tools defined with the @tool decorator on an instance or a plain object of fns. */
+export function collectTools(obj: object): Tool[] {
+  const fromInstance = REGISTRY.get(obj) ?? []
+  const fromProps: Tool[] = []
+  for (const key of Object.keys(obj)) {
+    const v = (obj as any)[key]
+    if (typeof v === "function" && v.__tool) fromProps.push(v.__tool)
+  }
+  return [...fromInstance, ...fromProps]
+}

package/src/skill.ts

@@ -0,0 +1,195 @@
+/**
+ * Dynamic agent-skill source. Mirrors opencode's skill/index.ts + tool/skill.ts:
+ * discover **\/SKILL.md, parse frontmatter, and expose ONE `skill` tool that
+ * loads a skill's instructions + sampled resources on demand (progressive
+ * disclosure).
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+import type { Tool, ToolResult } from "./types.js"
+
+export const SKILL_TOOL_DESCRIPTION = `Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
+
+Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
+
+The skill name must match one of the skills listed in your system prompt.`
+
+export interface SkillInfo {
+  name: string
+  description?: string
+  location: string // absolute path to SKILL.md
+  content: string // body after frontmatter
+}
+
+/** Minimal YAML frontmatter parser — only flat `key: value` pairs are needed. */
+function parseFrontmatter(text: string): { data: Record<string, string>; content: string } {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text)
+  if (!match) return { data: {}, content: text }
+  const data: Record<string, string> = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const idx = line.indexOf(":")
+    if (idx === -1) continue
+    const key = line.slice(0, idx).trim()
+    let value = line.slice(idx + 1).trim()
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1)
+    }
+    if (key) data[key] = value
+  }
+  return { data, content: match[2] }
+}
+
+function walkSkillFiles(root: string): string[] {
+  const out: string[] = []
+  const stack = [root]
+  while (stack.length) {
+    const dir = stack.pop()!
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue
+        stack.push(full)
+      } else if (entry.isFile() && entry.name === "SKILL.md") {
+        out.push(full)
+      }
+    }
+  }
+  return out
+}
+
+function sampleSiblingFiles(dir: string, limit = 10): string[] {
+  const out: string[] = []
+  const stack = [dir]
+  while (stack.length && out.length < limit) {
+    const cur = stack.pop()!
+    let entries
+    try {
+      entries = readdirSync(cur, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (out.length >= limit) break
+      const full = path.join(cur, entry.name)
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git") continue
+        stack.push(full)
+      } else if (entry.isFile() && entry.name !== "SKILL.md") {
+        out.push(full)
+      }
+    }
+  }
+  return out
+}
+
+export interface SkillSource {
+  skills: Record<string, SkillInfo>
+  tool: Tool
+  /** Markdown catalog for the system prompt (mirrors opencode Skill.fmt). */
+  prompt(): string
+}
+
+/** Discover skills under one or more roots and build the `skill` loader tool. */
+export function loadSkills(dirs: string | string[]): SkillSource {
+  const roots = Array.isArray(dirs) ? dirs : [dirs]
+  const skills: Record<string, SkillInfo> = {}
+
+  for (const root of roots) {
+    let isDir = false
+    try {
+      isDir = statSync(root).isDirectory()
+    } catch {
+      isDir = false
+    }
+    if (!isDir) {
+      console.warn(`[toolnexus] skills dir not found: ${root}`)
+      continue
+    }
+    for (const file of walkSkillFiles(root)) {
+      let text: string
+      try {
+        text = readFileSync(file, "utf8")
+      } catch {
+        continue
+      }
+      const { data, content } = parseFrontmatter(text)
+      if (!data.name) continue
+      if (skills[data.name]) {
+        console.warn(`[toolnexus] duplicate skill name "${data.name}" (${file}) — keeping first`)
+        continue
+      }
+      skills[data.name] = {
+        name: data.name,
+        description: data.description,
+        location: file,
+        content,
+      }
+    }
+  }
+
+  const tool: Tool = {
+    name: "skill",
+    description: SKILL_TOOL_DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string", description: "The name of the skill to load" } },
+      required: ["name"],
+      additionalProperties: false,
+    },
+    source: "skill",
+    async execute(args: Record<string, unknown>): Promise<ToolResult> {
+      const name = String(args?.name ?? "")
+      const info = skills[name]
+      if (!info) {
+        return {
+          output: `Skill "${name}" not found. Available skills: ${Object.keys(skills).sort().join(", ") || "none"}`,
+          isError: true,
+        }
+      }
+      const dir = path.dirname(info.location)
+      const base = pathToFileURL(dir).href
+      const files = sampleSiblingFiles(dir)
+      const output = [
+        `<skill_content name="${info.name}">`,
+        `# Skill: ${info.name}`,
+        "",
+        info.content.trim(),
+        "",
+        `Base directory for this skill: ${base}`,
+        "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
+        "Note: file list is sampled.",
+        "",
+        "<skill_files>",
+        files.map((f) => `<file>${f}</file>`).join("\n"),
+        "</skill_files>",
+        "</skill_content>",
+      ].join("\n")
+      return { output, isError: false, metadata: { name: info.name, dir } }
+    },
+  }
+
+  return {
+    skills,
+    tool,
+    prompt() {
+      const described = Object.values(skills)
+        .filter((s) => s.description !== undefined)
+        .sort((a, b) => a.name.localeCompare(b.name))
+      if (described.length === 0) return "No skills are currently available."
+      return [
+        "## Available Skills",
+        ...described.map((s) => `- **${s.name}**: ${s.description}`),
+      ].join("\n")
+    },
+  }
+}

package/src/toolkit.ts

@@ -0,0 +1,93 @@
+/**
+ * Toolkit — aggregates dynamic MCP tools + the skill tool + custom tools into a
+ * single uniform list, with provider adapters and a single execute() router.
+ */
+import { type Tool, type ToolContext, type ToolResult, type McpStatus } from "./types.js"
+import { loadMcp, type McpSource } from "./mcp.js"
+import { loadSkills, type SkillSource } from "./skill.js"
+import { toAnthropic, toGemini, toOpenAI } from "./adapters.js"
+
+export interface ToolkitOptions {
+  mcpConfig?: string | object
+  skillsDir?: string | string[]
+  extraTools?: Tool[]
+}
+
+export class Toolkit {
+  private byName = new Map<string, Tool>()
+  private constructor(
+    private readonly mcp: McpSource | undefined,
+    private readonly skill: SkillSource | undefined,
+    extraTools: Tool[],
+  ) {
+    const all = [...(mcp?.tools ?? []), ...(skill ? [skill.tool] : []), ...extraTools]
+    for (const t of all) {
+      if (this.byName.has(t.name)) {
+        console.warn(`[toolnexus] duplicate tool name "${t.name}" — keeping first`)
+        continue
+      }
+      this.byName.set(t.name, t)
+    }
+  }
+
+  static async create(opts: ToolkitOptions): Promise<Toolkit> {
+    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig) : undefined
+    const skill = opts.skillsDir !== undefined ? loadSkills(opts.skillsDir) : undefined
+    return new Toolkit(mcp, skill, opts.extraTools ?? [])
+  }
+
+  tools(): Tool[] {
+    return [...this.byName.values()]
+  }
+
+  get(name: string): Tool | undefined {
+    return this.byName.get(name)
+  }
+
+  /** Add a tool at runtime (native, http, or any custom Tool). First name wins. */
+  register(...tools: Tool[]): this {
+    for (const t of tools) {
+      if (this.byName.has(t.name)) {
+        console.warn(`[toolnexus] duplicate tool name "${t.name}" — keeping first`)
+        continue
+      }
+      this.byName.set(t.name, t)
+    }
+    return this
+  }
+
+  async execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult> {
+    const tool = this.byName.get(name)
+    if (!tool) {
+      return { output: `Unknown tool: ${name}`, isError: true }
+    }
+    return tool.execute(args ?? {}, ctx)
+  }
+
+  /** Markdown skill catalog for the system prompt. */
+  skillsPrompt(): string {
+    return this.skill ? this.skill.prompt() : ""
+  }
+
+  mcpStatus(): Record<string, McpStatus> {
+    return this.mcp?.status ?? {}
+  }
+
+  toOpenAI() {
+    return toOpenAI(this.tools())
+  }
+  toAnthropic() {
+    return toAnthropic(this.tools())
+  }
+  toGemini() {
+    return toGemini(this.tools())
+  }
+
+  async close(): Promise<void> {
+    await this.mcp?.close()
+  }
+}
+
+export function createToolkit(opts: ToolkitOptions): Promise<Toolkit> {
+  return Toolkit.create(opts)
+}

package/src/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared contract types. See ../../SPEC.md.
+ */
+
+export type JSONSchema = {
+  type: "object"
+  properties?: Record<string, unknown>
+  required?: string[]
+  additionalProperties?: boolean
+  [k: string]: unknown
+}
+
+export type ToolSource = "mcp" | "skill" | "native" | "http" | "custom"
+
+export interface ToolResult {
+  output: string
+  isError: boolean
+  metadata?: Record<string, unknown>
+}
+
+export interface ToolContext {
+  signal?: AbortSignal
+  timeout?: number
+}
+
+export interface Tool {
+  name: string
+  description: string
+  inputSchema: JSONSchema
+  source: ToolSource
+  execute(args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>
+}
+
+export type McpStatus = "connected" | "disabled" | "failed"
+
+/** Replace anything outside [a-zA-Z0-9_-] with "_" (same as opencode). */
+export const sanitize = (value: string) => value.replace(/[^a-zA-Z0-9_-]/g, "_")