@mcpc-tech/core 0.2.2 → 0.2.3

package/README.md

@@ -0,0 +1,163 @@
+# @mcpc/core
+
+**Build agentic MCP servers by composing existing MCP tools.**
+
+The core SDK for creating agentic Model Context Protocol (MCP) servers. Compose
+existing MCP tools into powerful AI agents with simple descriptions and tool
+references.
+
+## Installation
+
+```bash
+# npm (from npm registry)
+npm install @mcpc-tech/core
+
+# npm (from jsr)
+npx jsr add @mcpc/core
+
+# deno
+deno add jsr:@mcpc/core
+
+# pnpm (from npm registry)
+pnpm add @mcpc-tech/core
+
+# pnpm (from jsr)
+pnpm add jsr:@mcpc/core
+```
+
+## Quick Start
+
+```typescript
+import { mcpc } from "@mcpc/core";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// Create an agentic MCP server
+const server = await mcpc(
+  [
+    { name: "my-agent", version: "1.0.0" },
+    { capabilities: { tools: {}, sampling: {} } },
+  ],
+  [{
+    name: "my-agent",
+    description: `
+      I am a coding assistant that can read files and run terminal commands.
+      
+      Available tools:
+      <tool name="desktop-commander.read_file"/>
+      <tool name="desktop-commander.execute_command"/>
+    `,
+    deps: {
+      mcpServers: {
+        "desktop-commander": {
+          command: "npx",
+          args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
+          transportType: "stdio",
+        },
+      },
+    },
+    options: { mode: "agentic" },
+  }],
+);
+
+// Connect to stdio transport
+await server.connect(new StdioServerTransport());
+```
+
+## Key Concepts
+
+### Tool References
+
+Reference tools in your agent description using XML-like syntax:
+
+```typescript
+description: `
+  Available tools:
+  <tool name="server.tool"/>              // Basic reference
+  <tool name="server.__ALL__"/>           // All tools from server
+  <tool name="tool" maxResultLength="2000"/> // Limit result size
+  <tool name="tool" hide/>                // Hide from public interface
+  <tool name="tool" global/>              // Expose at global scope
+`;
+```
+
+### MCP Server Dependencies
+
+Support all MCP transport types:
+
+```typescript
+deps: {
+  mcpServers: {
+    "stdio-server": {
+      command: "npx",
+      args: ["-y", "some-mcp-server"],
+      transportType: "stdio"
+    },
+    "http-server": {
+      transportType: "streamable-http",
+      url: "https://api.example.com/mcp/",
+      headers: { "Authorization": "Bearer ${TOKEN}" }
+    },
+    "sse-server": {
+      transportType: "sse",
+      url: "https://api.example.com/sse/"
+    }
+  }
+}
+```
+
+### Execution Modes
+
+- **`agentic`** (default): Fully autonomous agent without structured workflow
+- **`agentic_workflow`**: Structured workflow with predefined or
+  runtime-generated steps
+
+### Plugins
+
+Extend functionality with plugins:
+
+```typescript
+import { createLargeResultPlugin } from "@mcpc/core/plugins";
+
+{
+  plugins: [
+    createLargeResultPlugin({ maxSize: 8000 }),
+    "./plugins/custom.ts?param=value",
+  ];
+}
+```
+
+## API Reference
+
+### `mcpc(serverConf, composeConf?, setupCallback?)`
+
+Main entry point for creating agentic MCP servers.
+
+**Parameters:**
+
+- `serverConf` - Server metadata and capabilities
+- `composeConf` - Array of agent composition definitions (optional)
+- `setupCallback` - Callback for custom setup before composition (optional)
+
+**Returns:** `Promise<ComposableMCPServer>`
+
+See [full documentation](../../docs/README.md) for detailed usage.
+
+## Examples
+
+Find complete examples in the [`examples/`](./examples/) directory:
+
+- `01-basic-composition.ts` - Basic agent composition
+- `02-plugin-usage.ts` - Using plugins
+- `03-agentic-workflow.ts` - Workflow mode with steps
+- `04-sampling-mode.ts` - Autonomous execution with sampling
+
+## Documentation
+
+- [Full Documentation](../../docs/README.md)
+- [Plugin System Guide](../../docs/plugins.md)
+- [Creating Your First Agentic MCP](../../docs/quickstart/create-your-first-agentic-mcp.md)
+- [FAQ](../../docs/faq.md)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpc-tech/core",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "homepage": "https://jsr.io/@mcpc/core",
   "type": "module",
   "dependencies": {

package/types/src/set-up-mcp-compose.d.ts

@@ -64,5 +64,67 @@ export interface ComposibleMCPConfig {
   [key: string]: ComposeDefinition[];
 }
 export declare function parseMcpcConfigs(conf?: ComposeDefinition[]): ComposeDefinition[];
-export declare function mcpc(serverConf: ConstructorParameters<typeof ComposableMCPServer>, composeConf?: ComposeDefinition[], setupCallback?: (server: ComposableMCPServer) => void | Promise<void>): Promise<InstanceType<typeof ComposableMCPServer>>;
+/**
+ * Create and configure an agentic MCP server with composed tools.
+ *
+ * This is the main entry point for building agentic MCP servers. It allows you to:
+ * - Reuse existing MCP tools from the community by selecting and composing them
+ * - Create powerful agentic tools by describing them in natural language with tool references
+ * - Fine-tune tool descriptions and parameters to fit your specific use cases
+ * - Build multi-agent systems where each agent is itself an MCP tool
+ *
+ * @example
+ * ```typescript
+ * const server = await mcpc(
+ *   [
+ *     { name: "coding-agent", version: "1.0.0" },
+ *     { capabilities: { tools: {}, sampling: {} } }
+ *   ],
+ *   [{
+ *     name: "codex-fork",
+ *     description: `A coding agent that can read files, search code, and create PRs.
+ *       Available tools:
+ *       <tool name="desktop-commander.read_file"/>
+ *       <tool name="github.create_pull_request"/>`,
+ *     deps: {
+ *       mcpServers: {
+ *         "desktop-commander": {
+ *           command: "npx",
+ *           args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
+ *           transportType: "stdio"
+ *         },
+ *         "github": {
+ *           transportType: "streamable-http",
+ *           url: "https://api.githubcopilot.com/mcp/",
+ *           headers: { "Authorization": `Bearer ${process.env.GITHUB_TOKEN}` }
+ *         }
+ *       }
+ *     },
+ *     plugins: [createLargeResultPlugin({ maxSize: 8000 })],
+ *     options: { mode: "agentic", sampling: true }
+ *   }]
+ * );
+ * await server.connect(new StdioServerTransport());
+ * ```
+ *
+ * @param serverConf - MCP server initialization parameters including name, version, and capabilities
+ *   - First element: Server metadata (name, version)
+ *   - Second element: Server capabilities (tools, sampling, etc.)
+ *
+ * @param composeConf - Array of agent composition definitions. Each definition includes:
+ *   - name: Agent name (set to null for composition-only mode)
+ *   - description: Agent purpose with XML-like tool references (e.g., `<tool name="server.tool"/>`)
+ *   - deps: MCP server dependencies with transport configurations (stdio, sse, streamable-http)
+ *   - plugins: Global plugins to transform/extend tool behavior (objects or file paths)
+ *   - options: Execution mode settings (agentic, agentic_workflow, sampling)
+ *
+ * @param setupCallback - Optional callback to register custom tools or perform additional setup
+ *   before composition. Useful for adding internal tools or custom configurations.
+ *
+ * @returns A configured MCP Server instance ready to connect to a transport
+ *
+ * @see {@link ComposeDefinition} for detailed composition configuration options
+ * @see {@link ToolPlugin} for plugin development guide
+ * @see https://github.com/mcpc-tech/mcpc/tree/main/docs for complete documentation
+ */ export declare function mcpc(serverConf: ConstructorParameters<typeof ComposableMCPServer>, composeConf?: ComposeDefinition[], setupCallback?: (server: ComposableMCPServer) => void | Promise<void>): Promise<InstanceType<typeof ComposableMCPServer>>;
 //# sourceMappingURL=set-up-mcp-compose.d.ts.map

package/types/src/set-up-mcp-compose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set-up-mcp-compose.d.ts","sources":["../../src/set-up-mcp-compose.ts"],"names":[],"mappings":"AAAA,SAAS,mBAAmB,oBAAoB;AAEhD,cAAc,QAAQ,2BAA2B;AACjD,cAAc,UAAU,6BAA6B;AACrD,cAAc,cAAc,qBAAqB;AACjD,cAAc,UAAU,4BAA4B;AACpD,cAAc,UAAU,qBAAqB;AAE7C,iBAAiB;EACf;;;GAGC,GACD,MAAM,MAAM,GAAG,IAAI;EACnB;;GAEC,GACD,cAAc,MAAM;EACpB,OAAO;EAEP;;;;;;;;;;;GAWC,GACD,WAAW,aAAa,MAAM;EAE9B;IACE;;;;;KAKC,GACD,OAAO,YAAY;IAEnB;;;;KAIC,GACD,WAAW,OAAO,GAAG;IAErB;;;;;KAKC,GACD,QAAQ;IAER;;;;;KAKC,GACD,oBAAoB,MAAM;IAE1B;;;;;KAKC,GACD;;;KAGC,GACD,OAAO,MAAM;;;AAMjB,iBAAiB;GACd,KAAK,MAAM,GAAG;;AAGjB,OAAO,iBAAS,iBACd,OAAO,mBAAmB,GACzB;AAuBH,OAAO,iBAAe,KACpB,YAAY,6BAA6B,oBAAoB,EAC7D,cAAc,mBAAmB,EACjC,iBAAiB,QAAQ,wBAAwB,IAAI,GAAG,QAAQ,IAAI,CAAC,GACpE,QAAQ,oBAAoB"}
+{"version":3,"file":"set-up-mcp-compose.d.ts","sources":["../../src/set-up-mcp-compose.ts"],"names":[],"mappings":"AAAA,SAAS,mBAAmB,oBAAoB;AAEhD,cAAc,QAAQ,2BAA2B;AACjD,cAAc,UAAU,6BAA6B;AACrD,cAAc,cAAc,qBAAqB;AACjD,cAAc,UAAU,4BAA4B;AACpD,cAAc,UAAU,qBAAqB;AAE7C,iBAAiB;EACf;;;GAGC,GACD,MAAM,MAAM,GAAG,IAAI;EACnB;;GAEC,GACD,cAAc,MAAM;EACpB,OAAO;EAEP;;;;;;;;;;;GAWC,GACD,WAAW,aAAa,MAAM;EAE9B;IACE;;;;;KAKC,GACD,OAAO,YAAY;IAEnB;;;;KAIC,GACD,WAAW,OAAO,GAAG;IAErB;;;;;KAKC,GACD,QAAQ;IAER;;;;;KAKC,GACD,oBAAoB,MAAM;IAE1B;;;;;KAKC,GACD;;;KAGC,GACD,OAAO,MAAM;;;AAMjB,iBAAiB;GACd,KAAK,MAAM,GAAG;;AAGjB,OAAO,iBAAS,iBACd,OAAO,mBAAmB,GACzB;AAuBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8DC,GACD,OAAO,iBAAe,KACpB,YAAY,6BAA6B,oBAAoB,EAC7D,cAAc,mBAAmB,EACjC,iBAAiB,QAAQ,wBAAwB,IAAI,GAAG,QAAQ,IAAI,CAAC,GACpE,QAAQ,oBAAoB"}