Mcpc Core

# Deno (preferred in this repo)
deno add jsr:@mcpc/core

# npm
npm install @mcpc-tech/core

# pnpm (from JSR)
pnpm add jsr:@mcpc/core

import { mcpc } from "@mcpc/core";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = await mcpc(
  [{ name: "my-agent", version: "1.0.0" }, { capabilities: { tools: {} } }],
  [{
    name: "file-agent",
    description: `I help manage files.
Available tools:
<tool name="@wonderwhy-er/desktop-commander.read_file"/>
<tool name="@wonderwhy-er/desktop-commander.write_file"/>`,
    deps: {
      mcpServers: {
        "@wonderwhy-er/desktop-commander": {
          command: "npx",
          args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
          transportType: "stdio",
        },
      },
    },
  }],
);

await server.connect(new StdioServerTransport());

{
  name: string | null,          // null = composition-only (no tool exposed)
  description?: string,         // Natural language + <tool> XML refs
  manual?: string,              // Progressive disclosure: long docs hidden behind man tool
  deps?: MCPSetting,            // Dependent MCP servers to connect
  plugins?: (ToolPlugin | string)[],  // Runtime plugins
  options?: {
    mode?: "agentic" | "ai_sampling" | "ai_acp",  // default: "agentic"
    maxSteps?: number,          // default: 50
    maxTokens?: number,         // default: 128_000 (ai_sampling only)
    samplingConfig?: SamplingConfig,
    providerOptions?: { modelPreferences?: {...} },  // ai_sampling only
    acpSettings?: { command, args, env, session, persistSession },  // ai_acp only
    tracingEnabled?: boolean,   // OpenTelemetry
    refs?: ToolRefXml[],
  }
}

<tool name="server.tool_name"/>              — specific tool
<tool name="server.__ALL__"/>               — all tools from a server
<tool name="server.tool" maxResultLength="2000"/>  — truncate large results
<tool name="server.tool" hide/>             — use internally, hide from public API
<tool name="server.tool" global/>           — expose at top-level scope

// stdio
"my-server": { command: "npx", args: ["-y", "pkg@latest"], transportType: "stdio" }

// Streamable HTTP
"remote": { transportType: "streamable-http", url: "https://api.example.com/mcp/",
            headers: { "Authorization": "Bearer ${TOKEN}" } }

// SSE
"sse-server": { transportType: "sse", url: "https://api.example.com/sse/" }

import {
  createBashPlugin, // Add bash execution tool
  createLargeResultPlugin, // Truncate/paginate large tool results
  createSearchPlugin, // Add ripgrep-based search tool
  createSkillsPlugin, // Lazy-load skill knowledge
} from "@mcpc/core/plugins";

// In ComposeDefinition
plugins: [
  createLargeResultPlugin({ maxSize: 8000 }),
  createSkillsPlugin({ paths: [".agents/skills"] }),
  createBashPlugin(),
  "./my-plugin.ts?param=value", // File path with query params
];

// Or in mcpc() options (loader plugins, run before composition)
await mcpc(serverConf, composeConf, {
  plugins: ["@mcpc/plugin-markdown-loader"],
});

import type { ToolPlugin } from "@mcpc/core";

const myPlugin: ToolPlugin = {
  name: "my-plugin",

  // Mutate/filter tool descriptions at compose time
  transformTool?: (tool: ComposedTool, ctx: TransformContext) => ComposedTool,

  // Intercept inputs before execution
  transformInput?: (args: unknown, ctx: BeforeToolExecuteContext) => unknown,

  // Intercept outputs after execution
  transformOutput?: (result: unknown, ctx: AfterToolExecuteContext) => unknown,

  // Lifecycle hooks
  onComposeStart?: (ctx: ComposeStartContext) => void,
  onComposeEnd?: (ctx: ComposeEndContext) => void,
  onFinalize?: (ctx: FinalizeContext) => void,
};

createSkillsPlugin({
  paths: [join(projectRoot, ".agents/skills")],
});

.agents/skills/
└── my-skill/
    ├── SKILL.md          ← main instructions (loaded by default)
    └── references/
        └── api.md        ← loaded via { skill, ref: "references/api.md" }

agent__load-skill({ skill: "my-skill" })
agent__load-skill({ skill: "my-skill", ref: "references/api.md" })

await mcpc(
  [{ name: "server", version: "1.0.0" }, { capabilities: { tools: {} } }],
  ["./agents/my-agent.md"],
  { plugins: ["@mcpc/plugin-markdown-loader"] },
);

---
name: my-agent
deps:
  mcpServers:
    some-server:
      command: npx
      args: ["-y", "some-server"]
      transportType: stdio
options:
  mode: agentic
---

I am an agent that does X.

<tool name="some-server.tool"/>

import { jsonSchema } from "@mcpc/core";

await mcpc(serverConf, composeConf, {
  setup: async (server) => {
    server.tool(
      "my-tool",
      "Description of tool",
      jsonSchema({ type: "object", properties: { input: { type: "string" } } }),
      async (args) => ({
        content: [{ type: "text", text: `Got: ${args.input}` }],
      }),
    );
    await server.addPlugin(myPlugin);
  },
});