toolnexus 0.1.0

package/dist/mcp.js

@@ -0,0 +1,169 @@
+/**
+ * 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 { sanitize } from "./types.js";
+const DEFAULT_TIMEOUT = 30_000;
+const MAX_LIST_PAGES = 1_000;
+function isRemote(cfg) {
+    if (cfg.type === "remote")
+        return true;
+    if (cfg.type === "local")
+        return false;
+    return "url" in cfg && typeof cfg.url === "string";
+}
+function isEnabled(cfg) {
+    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) {
+    const raw = typeof input === "string" ? JSON.parse(readFileSync(input, "utf8")) : input;
+    const servers = raw.mcpServers ?? raw.servers ?? raw.mcp ?? raw;
+    return servers;
+}
+/**
+ * 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) {
+    if (!headers)
+        return undefined;
+    const out = {};
+    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) {
+    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) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.type === "text" &&
+        typeof value.text === "string");
+}
+function joinTextContent(content) {
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .flatMap((item) => (isTextContent(item) ? [item.text] : []))
+        .join("\n");
+}
+async function paginateTools(client, timeout) {
+    const result = [];
+    const cursors = new Set();
+    let cursor;
+    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, def, client, timeout) {
+    const inputSchema = {
+        ...def.inputSchema,
+        type: "object",
+        properties: (def.inputSchema?.properties ?? {}),
+        additionalProperties: false,
+    };
+    return {
+        name: sanitize(server) + "_" + sanitize(def.name),
+        description: def.description ?? "",
+        inputSchema,
+        source: "mcp",
+        async execute(args, ctx) {
+            try {
+                const result = 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 } };
+            }
+        },
+    };
+}
+/** Connect to every enabled server, list + convert tools. Failures are isolated. */
+export async function loadMcp(input) {
+    const config = parseMcpConfig(input);
+    const tools = [];
+    const status = {};
+    const clients = [];
+    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;
+                const [cmd, ...args] = local.command;
+                await client.connect(new StdioClientTransport({
+                    command: cmd,
+                    args,
+                    cwd: local.cwd,
+                    env: { ...process.env, ...(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/dist/native.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Native / annotation tools — turn a plain function into a uniform Tool.
+ * See ../../SPEC.md §6.
+ */
+import type { JSONSchema, Tool, ToolContext } 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>;
+}
+/** Wrap a function as a Tool. The run() return value becomes the tool output. */
+export declare function defineTool(opts: DefineToolOptions): Tool;
+export declare function tool(description: string, opts?: {
+    name?: string;
+    inputSchema?: JSONSchema;
+}): (value: any, context: any) => any;
+/** Gather tools defined with the @tool decorator on an instance or a plain object of fns. */
+export declare function collectTools(obj: object): Tool[];

package/dist/native.js

@@ -0,0 +1,57 @@
+const EMPTY_SCHEMA = { type: "object", properties: {}, additionalProperties: false };
+/** Wrap a function as a Tool. The run() return value becomes the tool output. */
+export function defineTool(opts) {
+    return {
+        name: opts.name,
+        description: opts.description,
+        inputSchema: opts.inputSchema ?? EMPTY_SCHEMA,
+        source: opts.source ?? "native",
+        async execute(args, ctx) {
+            try {
+                const out = await opts.run(args ?? {}, ctx);
+                if (out && typeof out === "object" && "output" in out && "isError" in out) {
+                    return out;
+                }
+                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();
+export function tool(description, opts) {
+    return function (value, context) {
+        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 () {
+                const list = REGISTRY.get(this) ?? [];
+                list.push(t);
+                REGISTRY.set(this, list);
+            });
+        }
+        ;
+        fn.__tool = t;
+        return value;
+    };
+}
+/** Gather tools defined with the @tool decorator on an instance or a plain object of fns. */
+export function collectTools(obj) {
+    const fromInstance = REGISTRY.get(obj) ?? [];
+    const fromProps = [];
+    for (const key of Object.keys(obj)) {
+        const v = obj[key];
+        if (typeof v === "function" && v.__tool)
+            fromProps.push(v.__tool);
+    }
+    return [...fromInstance, ...fromProps];
+}

package/dist/skill.d.ts

@@ -0,0 +1,16 @@
+import type { Tool } from "./types.js";
+export declare const SKILL_TOOL_DESCRIPTION = "Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.\n\nUse 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.\n\nThe skill name must match one of the skills listed in your system prompt.";
+export interface SkillInfo {
+    name: string;
+    description?: string;
+    location: string;
+    content: string;
+}
+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 declare function loadSkills(dirs: string | string[]): SkillSource;

package/dist/skill.js

@@ -0,0 +1,184 @@
+/**
+ * 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";
+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.`;
+/** Minimal YAML frontmatter parser — only flat `key: value` pairs are needed. */
+function parseFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+    if (!match)
+        return { data: {}, content: text };
+    const data = {};
+    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) {
+    const out = [];
+    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, limit = 10) {
+    const out = [];
+    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;
+}
+/** Discover skills under one or more roots and build the `skill` loader tool. */
+export function loadSkills(dirs) {
+    const roots = Array.isArray(dirs) ? dirs : [dirs];
+    const skills = {};
+    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;
+            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 = {
+        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) {
+            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/dist/toolkit.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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";
+export interface ToolkitOptions {
+    mcpConfig?: string | object;
+    skillsDir?: string | string[];
+    extraTools?: Tool[];
+}
+export declare class Toolkit {
+    private readonly mcp;
+    private readonly skill;
+    private byName;
+    private constructor();
+    static create(opts: ToolkitOptions): Promise<Toolkit>;
+    tools(): Tool[];
+    get(name: string): Tool | undefined;
+    /** Add a tool at runtime (native, http, or any custom Tool). First name wins. */
+    register(...tools: Tool[]): this;
+    execute(name: string, args: Record<string, unknown>, ctx?: ToolContext): Promise<ToolResult>;
+    /** Markdown skill catalog for the system prompt. */
+    skillsPrompt(): string;
+    mcpStatus(): Record<string, McpStatus>;
+    toOpenAI(): {
+        type: "function";
+        function: {
+            name: string;
+            description: string;
+            parameters: import("./types.js").JSONSchema;
+        };
+    }[];
+    toAnthropic(): {
+        name: string;
+        description: string;
+        input_schema: import("./types.js").JSONSchema;
+    }[];
+    toGemini(): {
+        functionDeclarations: {
+            name: string;
+            description: string;
+            parameters: import("./types.js").JSONSchema;
+        }[];
+    }[];
+    close(): Promise<void>;
+}
+export declare function createToolkit(opts: ToolkitOptions): Promise<Toolkit>;

package/dist/toolkit.js

@@ -0,0 +1,71 @@
+import { loadMcp } from "./mcp.js";
+import { loadSkills } from "./skill.js";
+import { toAnthropic, toGemini, toOpenAI } from "./adapters.js";
+export class Toolkit {
+    mcp;
+    skill;
+    byName = new Map();
+    constructor(mcp, skill, extraTools) {
+        this.mcp = mcp;
+        this.skill = skill;
+        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) {
+        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() {
+        return [...this.byName.values()];
+    }
+    get(name) {
+        return this.byName.get(name);
+    }
+    /** Add a tool at runtime (native, http, or any custom Tool). First name wins. */
+    register(...tools) {
+        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, args, ctx) {
+        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() {
+        return this.skill ? this.skill.prompt() : "";
+    }
+    mcpStatus() {
+        return this.mcp?.status ?? {};
+    }
+    toOpenAI() {
+        return toOpenAI(this.tools());
+    }
+    toAnthropic() {
+        return toAnthropic(this.tools());
+    }
+    toGemini() {
+        return toGemini(this.tools());
+    }
+    async close() {
+        await this.mcp?.close();
+    }
+}
+export function createToolkit(opts) {
+    return Toolkit.create(opts);
+}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare const sanitize: (value: string) => string;

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared contract types. See ../../SPEC.md.
+ */
+/** Replace anything outside [a-zA-Z0-9_-] with "_" (same as opencode). */
+export const sanitize = (value) => value.replace(/[^a-zA-Z0-9_-]/g, "_");

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "toolnexus",
+  "version": "0.1.0",
+  "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts",
+    "example": "node --experimental-strip-types examples/basic.ts"
+  },
+  "keywords": ["mcp", "llm", "agent", "skills", "tools", "openai", "anthropic", "gemini"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/src/adapters.ts

@@ -0,0 +1,33 @@
+/**
+ * Provider adapters — turn the uniform tool list into each LLM's tool schema.
+ * Execution is identical for every provider: read the tool name + args the model
+ * returned, call toolkit.execute(name, args), feed output back.
+ */
+import type { Tool } from "./types.js"
+
+export function toOpenAI(tools: Tool[]) {
+  return tools.map((t) => ({
+    type: "function" as const,
+    function: { name: t.name, description: t.description, parameters: t.inputSchema },
+  }))
+}
+
+export function toAnthropic(tools: Tool[]) {
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    input_schema: t.inputSchema,
+  }))
+}
+
+export function toGemini(tools: Tool[]) {
+  return [
+    {
+      functionDeclarations: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.inputSchema,
+      })),
+    },
+  ]
+}