Skip to content

Commit 7777071

Browse files
yaonyanyaonyan
committed
feat: update JSR to NPM conversion command and add detailed documentation for MCP server setup
1 parent 6d21bad commit 7777071

File tree

4 files changed

+239
-5
lines changed

4 files changed

+239
-5
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ jobs:
3737
run: deno publish
3838

3939
- name: Run JSR to NPM conversion
40-
run: npx -y @yaonyan/jsr2npm@latest "$(pwd)/jsr2npm.config.json"
40+
run: npx -y @yaonyan/jsr2npm@latest
4141

4242
- name: Publish to npm
4343
run: |

‎packages/core/README.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# @mcpc/core
2+
3+
**Build agentic MCP servers by composing existing MCP tools.**
4+
5+
The core SDK for creating agentic Model Context Protocol (MCP) servers. Compose
6+
existing MCP tools into powerful AI agents with simple descriptions and tool
7+
references.
8+
9+
## Installation
10+
11+
```bash
12+
# npm (from npm registry)
13+
npm install @mcpc-tech/core
14+
15+
# npm (from jsr)
16+
npx jsr add @mcpc/core
17+
18+
# deno
19+
deno add jsr:@mcpc/core
20+
21+
# pnpm (from npm registry)
22+
pnpm add @mcpc-tech/core
23+
24+
# pnpm (from jsr)
25+
pnpm add jsr:@mcpc/core
26+
```
27+
28+
## Quick Start
29+
30+
```typescript
31+
import { mcpc } from "@mcpc/core";
32+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
33+
34+
// Create an agentic MCP server
35+
const server = await mcpc(
36+
[
37+
{ name: "my-agent", version: "1.0.0" },
38+
{ capabilities: { tools: {}, sampling: {} } },
39+
],
40+
[{
41+
name: "my-agent",
42+
description: `
43+
I am a coding assistant that can read files and run terminal commands.
44+
45+
Available tools:
46+
<tool name="desktop-commander.read_file"/>
47+
<tool name="desktop-commander.execute_command"/>
48+
`,
49+
deps: {
50+
mcpServers: {
51+
"desktop-commander": {
52+
command: "npx",
53+
args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
54+
transportType: "stdio",
55+
},
56+
},
57+
},
58+
options: { mode: "agentic" },
59+
}],
60+
);
61+
62+
// Connect to stdio transport
63+
await server.connect(new StdioServerTransport());
64+
```
65+
66+
## Key Concepts
67+
68+
### Tool References
69+
70+
Reference tools in your agent description using XML-like syntax:
71+
72+
```typescript
73+
description: `
74+
Available tools:
75+
<tool name="server.tool"/> // Basic reference
76+
<tool name="server.__ALL__"/> // All tools from server
77+
<tool name="tool" maxResultLength="2000"/> // Limit result size
78+
<tool name="tool" hide/> // Hide from public interface
79+
<tool name="tool" global/> // Expose at global scope
80+
`;
81+
```
82+
83+
### MCP Server Dependencies
84+
85+
Support all MCP transport types:
86+
87+
```typescript
88+
deps: {
89+
mcpServers: {
90+
"stdio-server": {
91+
command: "npx",
92+
args: ["-y", "some-mcp-server"],
93+
transportType: "stdio"
94+
},
95+
"http-server": {
96+
transportType: "streamable-http",
97+
url: "https://api.example.com/mcp/",
98+
headers: { "Authorization": "Bearer ${TOKEN}" }
99+
},
100+
"sse-server": {
101+
transportType: "sse",
102+
url: "https://api.example.com/sse/"
103+
}
104+
}
105+
}
106+
```
107+
108+
### Execution Modes
109+
110+
- **`agentic`** (default): Fully autonomous agent without structured workflow
111+
- **`agentic_workflow`**: Structured workflow with predefined or
112+
runtime-generated steps
113+
114+
### Plugins
115+
116+
Extend functionality with plugins:
117+
118+
```typescript
119+
import { createLargeResultPlugin } from "@mcpc/core/plugins";
120+
121+
{
122+
plugins: [
123+
createLargeResultPlugin({ maxSize: 8000 }),
124+
"./plugins/custom.ts?param=value",
125+
];
126+
}
127+
```
128+
129+
## API Reference
130+
131+
### `mcpc(serverConf, composeConf?, setupCallback?)`
132+
133+
Main entry point for creating agentic MCP servers.
134+
135+
**Parameters:**
136+
137+
- `serverConf` - Server metadata and capabilities
138+
- `composeConf` - Array of agent composition definitions (optional)
139+
- `setupCallback` - Callback for custom setup before composition (optional)
140+
141+
**Returns:** `Promise<ComposableMCPServer>`
142+
143+
See [full documentation](../../docs/README.md) for detailed usage.
144+
145+
## Examples
146+
147+
Find complete examples in the [`examples/`](./examples/) directory:
148+
149+
- `01-basic-composition.ts` - Basic agent composition
150+
- `02-plugin-usage.ts` - Using plugins
151+
- `03-agentic-workflow.ts` - Workflow mode with steps
152+
- `04-sampling-mode.ts` - Autonomous execution with sampling
153+
154+
## Documentation
155+
156+
- [Full Documentation](../../docs/README.md)
157+
- [Plugin System Guide](../../docs/plugins.md)
158+
- [Creating Your First Agentic MCP](../../docs/quickstart/create-your-first-agentic-mcp.md)
159+
- [FAQ](../../docs/faq.md)
160+
161+
## License
162+
163+
MIT

‎packages/core/deno.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@mcpc/core",
3-
"version": "0.2.2",
3+
"version": "0.2.3",
44
"repository": {
55
"type": "git",
66
"url": "git+https://github.com/mcpc-tech/mcpc.git"

‎packages/core/src/set-up-mcp-compose.ts‎

Lines changed: 74 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,69 @@ export function parseMcpcConfigs(
109109
return newMcpcConfigs;
110110
}
111111

112+
/**
113+
* Create and configure an agentic MCP server with composed tools.
114+
*
115+
* This is the main entry point for building agentic MCP servers. It allows you to:
116+
* - Reuse existing MCP tools from the community by selecting and composing them
117+
* - Create powerful agentic tools by describing them in natural language with tool references
118+
* - Fine-tune tool descriptions and parameters to fit your specific use cases
119+
* - Build multi-agent systems where each agent is itself an MCP tool
120+
*
121+
* @example
122+
* ```typescript
123+
* const server = await mcpc(
124+
* [
125+
* { name: "coding-agent", version: "1.0.0" },
126+
* { capabilities: { tools: {}, sampling: {} } }
127+
* ],
128+
* [{
129+
* name: "codex-fork",
130+
* description: `A coding agent that can read files, search code, and create PRs.
131+
* Available tools:
132+
* <tool name="desktop-commander.read_file"/>
133+
* <tool name="github.create_pull_request"/>`,
134+
* deps: {
135+
* mcpServers: {
136+
* "desktop-commander": {
137+
* command: "npx",
138+
* args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
139+
* transportType: "stdio"
140+
* },
141+
* "github": {
142+
* transportType: "streamable-http",
143+
* url: "https://api.githubcopilot.com/mcp/",
144+
* headers: { "Authorization": `Bearer ${process.env.GITHUB_TOKEN}` }
145+
* }
146+
* }
147+
* },
148+
* plugins: [createLargeResultPlugin({ maxSize: 8000 })],
149+
* options: { mode: "agentic", sampling: true }
150+
* }]
151+
* );
152+
* await server.connect(new StdioServerTransport());
153+
* ```
154+
*
155+
* @param serverConf - MCP server initialization parameters including name, version, and capabilities
156+
* - First element: Server metadata (name, version)
157+
* - Second element: Server capabilities (tools, sampling, etc.)
158+
*
159+
* @param composeConf - Array of agent composition definitions. Each definition includes:
160+
* - name: Agent name (set to null for composition-only mode)
161+
* - description: Agent purpose with XML-like tool references (e.g., `<tool name="server.tool"/>`)
162+
* - deps: MCP server dependencies with transport configurations (stdio, sse, streamable-http)
163+
* - plugins: Global plugins to transform/extend tool behavior (objects or file paths)
164+
* - options: Execution mode settings (agentic, agentic_workflow, sampling)
165+
*
166+
* @param setupCallback - Optional callback to register custom tools or perform additional setup
167+
* before composition. Useful for adding internal tools or custom configurations.
168+
*
169+
* @returns A configured MCP Server instance ready to connect to a transport
170+
*
171+
* @see {@link ComposeDefinition} for detailed composition configuration options
172+
* @see {@link ToolPlugin} for plugin development guide
173+
* @see https://github.com/mcpc-tech/mcpc/tree/main/docs for complete documentation
174+
*/
112175
export async function mcpc(
113176
serverConf: ConstructorParameters<typeof ComposableMCPServer>,
114177
composeConf?: ComposeDefinition[],
@@ -117,15 +180,16 @@ export async function mcpc(
117180
const server = new ComposableMCPServer(...serverConf);
118181
const parsed = parseMcpcConfigs(composeConf);
119182

120-
// Initialize built-in plugins first
183+
// Initialize built-in plugins first (e.g., large result handler, search plugin)
121184
await server.initBuiltInPlugins();
122185

123186
// Load global plugins before composition
187+
// Plugins can transform tool descriptions, results, and behavior
124188
for (const mcpcConfig of parsed) {
125189
if (mcpcConfig.plugins) {
126190
for (const plugin of mcpcConfig.plugins) {
127191
if (typeof plugin === "string") {
128-
// Load global plugin from file
192+
// Load global plugin from file path (supports query params like ?maxSize=8000)
129193
await server.loadPluginFromPath(plugin);
130194
} else {
131195
// Register global plugin object directly
@@ -135,11 +199,18 @@ export async function mcpc(
135199
}
136200
}
137201

138-
// Allow user to register tools before composing
202+
// Allow user to register custom tools or perform additional setup before composing
203+
// Useful for adding internal tools or configuring server-specific behavior
139204
if (setupCallback) {
140205
await setupCallback(server);
141206
}
142207

208+
// Compose each agent by connecting to MCP dependencies and creating the agentic tool
209+
// This process:
210+
// 1. Parses tool references from the description
211+
// 2. Connects to dependent MCP servers (stdio, sse, streamable-http)
212+
// 3. Selects and composes referenced tools
213+
// 4. Creates the final agentic tool with chosen execution mode
143214
for (const mcpcConfig of parsed) {
144215
await server.compose(
145216
mcpcConfig.name,

0 commit comments

Comments
 (0)