refactor(mcpc): simplify API with AgentOptions and add defaults

- Add AgentOptions interface for advanced options (maxSteps, maxTokens, tracingEnabled, samplingConfig, providerOptions, acpSettings, refs)
- Simplify AgentDef from 13 fields to 6 fields (name, description, mcpServers, mode, plugins, options)
- Add global plugins support that apply to all agents
- Add default values: version='1.0.0', capabilities={ tools: { listChanged: true } }
- Add 'agent' singular field for simpler single-agent configs
- Add mcpc_api_test.ts with 10 tests covering new API
- Update examples to use new structure

Author: yaonyan

packages/cli/src/app.ts

@@ -1,6 +1,6 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { registerAgent } from "./controllers/register.ts";
-import { mcpc } from "@mcpc/core";
+import { mcpcLegacy } from "@mcpc/core";
 import { createLargeResultPlugin } from "@mcpc/core/plugins/large-result";
 import type { ComposableMCPServer, ComposeDefinition } from "@mcpc/core";
 import type { MCPCConfig } from "./config/loader.ts";
@@ -25,7 +25,7 @@ export const createServer = async (
     ] as ComposeDefinition[],
   };
 
-  return await mcpc(
+  return await mcpcLegacy(
     [
       {
         name: serverConfig.name || "mcpc-server",

packages/core/examples/01-basic-composition.ts

@@ -11,20 +11,27 @@
  */
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { type ComposeDefinition, mcpc } from "../mod.ts";
+import { mcpc } from "../mod.ts";
 
-export const toolDefinitions: ComposeDefinition[] = [
-  {
-    name: "file-organizer",
-    description:
-      `I am a smart file organizer that helps users manage their files efficiently.
+export const server = await mcpc({
+  name: "basic-file-manager",
+  version: "1.0.0",
+  capabilities: {
+    tools: { listChanged: true },
+  },
+
+  agents: [
+    {
+      name: "file-organizer",
+      description:
+        `I am a smart file organizer that helps users manage their files efficiently.
 
 Available tools:
 <tool name="@wonderwhy-er/desktop-commander.list_directory"/>
 <tool name="@wonderwhy-er/desktop-commander.create_directory"/>
 <tool name="@wonderwhy-er/desktop-commander.move_file"/>
 <tool name="@wonderwhy-er/desktop-commander.read_file"/>
-<tool name="@wonderwhy-er/desktop-commander.write_file">
+<tool name="@wonderwhy-er/desktop-commander.write_file"/>
 
 I can:
 1. List directory contents to understand the current file structure
@@ -36,34 +43,15 @@ I can:
 
 I always ask for confirmation before making destructive changes and provide clear explanations of what I'm doing.`,
 
-    deps: {
       mcpServers: {
         "@wonderwhy-er/desktop-commander": {
           command: "npx",
           args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
-          transportType: "stdio" as const,
-        },
-      },
-    },
-  },
-];
-
-export const server = await mcpc(
-  [
-    {
-      name: "basic-file-manager",
-      version: "1.0.0",
-    },
-    {
-      capabilities: {
-        tools: {
-          listChanged: true,
         },
       },
     },
   ],
-  toolDefinitions,
-);
+});
 
 const transport = new StdioServerTransport();
 await server.connect(transport);

packages/core/examples/02-agentic-data-analyst.ts

@@ -14,22 +14,15 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { mcpc } from "../mod.ts";
 
-export const server = await mcpc(
-  [
-    {
-      name: "agentic-data-analyst",
-      version: "1.0.0",
-    },
-    { capabilities: { tools: { listChanged: true } } },
-  ],
-  [
+export const server = await mcpc({
+  name: "agentic-data-analyst",
+  version: "1.0.0",
+  capabilities: { tools: { listChanged: true } },
+
+  agents: [
     {
       name: "data-analyst",
-
-      // Agentic mode for complete autonomy
-      options: {
-        mode: "agentic",
-      },
+      mode: "agentic",
 
       description:
         `I am an autonomous data analyst that can perform comprehensive data analysis with complete freedom to orchestrate my actions.
@@ -60,22 +53,18 @@ I decide the order of operations dynamically based on:
 
 My autonomous approach ensures thorough analysis tailored to each unique dataset.`,
 
-      deps: {
-        mcpServers: {
-          "code-runner": {
-            command: "deno",
-            args: ["run", "--allow-all", "jsr:@mcpc/code-runner-mcp/bin"],
-            transportType: "stdio",
-          },
-          "@wonderwhy-er/desktop-commander": {
-            command: "npx",
-            args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
-            transportType: "stdio",
-          },
+      mcpServers: {
+        "code-runner": {
+          command: "deno",
+          args: ["run", "--allow-all", "jsr:@mcpc/code-runner-mcp/bin"],
+        },
+        "@wonderwhy-er/desktop-commander": {
+          command: "npx",
+          args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
         },
       },
     },
   ],
-);
+});
 
 await server.connect(new StdioServerTransport());

packages/core/examples/06-multi-mcp-web-analyzer.ts

@@ -15,21 +15,15 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { mcpc } from "../mod.ts";
 
-export const server = await mcpc(
-  [
-    {
-      name: "multi-mcp-web-analyzer",
-      version: "1.0.0",
-    },
-    { capabilities: { tools: { listChanged: true } } },
-  ],
-  [
+export const server = await mcpc({
+  name: "multi-mcp-web-analyzer",
+  version: "1.0.0",
+  capabilities: { tools: { listChanged: true } },
+
+  agents: [
     {
       name: "web-analyzer",
-
-      options: {
-        mode: "agentic",
-      },
+      mode: "agentic",
 
       description:
         `I am a comprehensive web analyzer that combines multiple MCP servers to perform sophisticated web content analysis and reporting.
@@ -83,27 +77,22 @@ I intelligently coordinate between browser automation, data processing, and file
 - PDF reports for sharing and presentation
 - Screenshots and visual documentation`,
 
-      deps: {
-        mcpServers: {
-          "@microsoft/playwright-mcp": {
-            command: "npx",
-            args: ["@playwright/mcp@latest", "--image-responses=emit"],
-            transportType: "stdio",
-          },
-          "code-runner": {
-            command: "deno",
-            args: ["run", "--allow-all", "jsr:@mcpc/code-runner-mcp/bin"],
-            transportType: "stdio",
-          },
-          "@wonderwhy-er/desktop-commander": {
-            command: "npx",
-            args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
-            transportType: "stdio",
-          },
+      mcpServers: {
+        "@microsoft/playwright-mcp": {
+          command: "npx",
+          args: ["@playwright/mcp@latest", "--image-responses=emit"],
+        },
+        "code-runner": {
+          command: "deno",
+          args: ["run", "--allow-all", "jsr:@mcpc/code-runner-mcp/bin"],
+        },
+        "@wonderwhy-er/desktop-commander": {
+          command: "npx",
+          args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
         },
       },
     },
   ],
-);
+});
 
 await server.connect(new StdioServerTransport());

packages/core/examples/07-runtime-transformations.ts

@@ -119,15 +119,17 @@ const _errorEnrichmentPlugin: ToolPlugin = {
 
 // Example usage
 async function main() {
-  const server = await mcpc(
-    [{ name: "example-server", version: "1.0.0" }, {}],
-    [],
-    async (server) => {
-      // Add runtime transformation plugins
-      await server.addPlugin(inputSanitizationPlugin);
-      await server.addPlugin(outputFormattingPlugin);
-      await server.addPlugin(loggingPlugin);
+  const server = await mcpc({
+    name: "example-server",
+    version: "1.0.0",
 
+    plugins: [
+      inputSanitizationPlugin,
+      outputFormattingPlugin,
+      loggingPlugin,
+    ],
+
+    setup: (server) => {
       // Register a sample tool
       server.tool(
         "greet",
@@ -151,7 +153,7 @@ async function main() {
         },
       );
     },
-  );
+  });
 
   // Test the tool - input will be sanitized, output will be formatted and logged
   const result = await server.callTool("greet", {

packages/core/examples/09-unified-prompt-management.ts

@@ -98,37 +98,31 @@ const agentDescription = fileOperationsDescription
   .replace("{hiddenTools}", hiddenTools)
   .replace("{wildcardTools}", wildcardTools);
 
-export const server = await mcpc(
-  [
-    {
-      name: "unified-prompt-manager",
-      version: "1.0.0",
-    },
-    { capabilities: { tools: { listChanged: true } } },
-  ],
-  [
+export const server = await mcpc({
+  name: "unified-prompt-manager",
+  version: "1.0.0",
+  capabilities: { tools: { listChanged: true } },
+
+  agents: [
     {
       name: "prompt-managed-agent",
-
-      // Use centralized description template
       description: agentDescription,
 
-      deps: {
-        mcpServers: {
-          "@wonderwhy-er/desktop-commander": {
-            command: "npx",
-            args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
-          },
-          "code-runner": {
-            command: "deno",
-            args: ["run", "--allow-all", "jsr:@mcpc/code-runner-mcp/bin"],
-          },
+      mcpServers: {
+        "@wonderwhy-er/desktop-commander": {
+          command: "npx",
+          args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
+        },
+        "code-runner": {
+          command: "deno",
+          args: ["run", "--allow-all", "jsr:@mcpc/code-runner-mcp/bin"],
         },
       },
     },
   ],
+
   // Demonstrate internal tool registration with centralized prompts
-  (server) => {
+  setup: (server) => {
     server.tool(
       "audit-logger",
       "Internal comprehensive audit logging with standardized format",
@@ -228,6 +222,6 @@ export const server = await mcpc(
       "📝 All prompts are now centrally managed and dynamically generated",
     );
   },
-);
+});
 
 await server.connect(new StdioServerTransport());

packages/core/examples/11-large-result-plugin-agentic.ts

@@ -6,25 +6,26 @@
  */
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { mcpc } from "../src/set-up-mcp-compose.ts";
-// import { createLargeResultPlugin } from "../plugins.ts";
+import { mcpc } from "../mod.ts";
 import { jsonSchema } from "../mod.ts";
 
-const server = await mcpc(
-  [{ name: "large-demo", version: "1.0.0" }, { capabilities: { tools: {} } }],
-  [
+const server = await mcpc({
+  name: "large-demo",
+  version: "1.0.0",
+  capabilities: { tools: {} },
+
+  agents: [
     {
       name: "large-output-handler",
       description:
         "Agent that demonstrates automatic large output handling and file storage",
       plugins: [
         "./plugins/large-result.ts?maxSize=8000&previewSize=4000",
-        // create a large result plugin instance
-        // createLargeResultPlugin(),
       ],
     },
   ],
-  (server) => {
+
+  setup: (server) => {
     // Tool that makes big output
     server.tool(
       "make-big-text",
@@ -46,7 +47,7 @@ const server = await mcpc(
       { internal: true },
     );
   },
-);
+});
 
 const transport = new StdioServerTransport();
 await server.connect(transport);