Skip to content

Commit 632b1d0

Browse files
yaonyanyaonyan
committed
feat: add comprehensive documentation for MCPC, including quickstart guides, examples, and FAQs
1 parent 84a1869 commit 632b1d0

File tree

9 files changed

+571
-280
lines changed

9 files changed

+571
-280
lines changed

‎README.md‎

Lines changed: 108 additions & 280 deletions
Large diffs are not rendered by default.

‎docs/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# MCPC Documentation
2+
3+
MCP Compose is the SDK for building agentic MCP(Model Context Protocol) Servers.
4+
You can use it to:
5+
6+
1. **Create Powerful Agentic MCP Tools:** Simply describe your vision in text
7+
and reference a vast array of tools from the
8+
[expanding MCP community](https://registry.modelcontextprotocol.io/docs#/operations/list-servers),
9+
rapidly transforming your ideas into powerful agents.
10+
2. **Fine-Tune Existing Tools:** Flexibly modify existing tool descriptions and
11+
parameters, or wrap and filter results to precisely adapt them to your
12+
specific business scenarios.
13+
3. **Build Multi-Agent Systems:** By defining each agent as a MCP tool, you can
14+
compose and orchestrate them to construct sophisticated, collaborative
15+
multi-agent systems.
16+
17+
# Quickstart
18+
19+
[Installation](./quickstart/installation.md)
20+
21+
[Create your first agentic MCP](./quickstart/create-your-first-agentic-mcp.md)
22+
23+
[AI SDK Integration](./quickstart/ai-sdk-integration.md)
24+
25+
# Examples
26+
27+
[Creating a codex fork](./examples/creating-a-codex-fork.md)
28+
29+
# Learn more
30+
31+
[Agentic MCP Tools](./learn-more/agentic-mcp-tools.md)
32+
33+
[Achieving Agent Interoperability](./learn-more/achieving-agent-interoperability.md)
34+
35+
# FAQ
36+
37+
[FAQ](./faq.md)

‎docs/examples/creating-a-codex-fork.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Creating a Codex fork
2+
3+
OpenAI's Codex a is an agent designed to be your software engineering teammate.
4+
5+
This guide will show you how to build your own version using the Agentic MCP
6+
framework. We'll create a "codex fork" agent that composes several tools to
7+
interact with your file system, terminal, and GitHub.
8+
9+
The entire agent can be defined in a single file. This includes defining
10+
dependencies, writing the agent's documentation for the LLM, and starting the
11+
server.
12+
13+
```typescript
14+
import { type ComposeDefinition, mcpc } from "@mcpc/core";
15+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
16+
17+
// 1. First, Collect Your MCP Server Dependencies
18+
// Define the existing MCP servers that your agent will depend on.
19+
const deps: ComposeDefinition["deps"] = {
20+
mcpServers: {
21+
"desktop-commander": {
22+
command: "npx",
23+
args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
24+
transportType: "stdio",
25+
},
26+
"lsmcp": {
27+
command: "npx",
28+
args: ["-y", "@mizchi/lsmcp", "-p", "tsgo"],
29+
transportType: "stdio",
30+
},
31+
"github": {
32+
transportType: "streamable-http",
33+
url: "https://api.githubcopilot.com/mcp/",
34+
headers: {
35+
// Note: You would typically use a secrets manager for API keys.
36+
"Authorization": "Bearer ${input:github_mcp_pat}",
37+
},
38+
},
39+
},
40+
};
41+
42+
// 2. Then, Write the Documentation for Your Agent
43+
// This documentation tells the LLM what the agent does, when to use it,
44+
// and how to reference its underlying tools using the <tool> syntax.
45+
const description = `
46+
You are a "codex fork" agent, a world-class AI assistant for coding tasks.
47+
48+
Your capabilities include:
49+
- Reading and writing files.
50+
- Searching the codebase using advanced language server features.
51+
- Executing terminal commands to build, test, and run projects.
52+
- Interacting with GitHub to create pull requests and manage issues.
53+
54+
To perform these actions, you must use the following tools:
55+
- To execute a shell command: <tool name="desktop-commander.exec" />
56+
- To read a file's content: <tool name="desktop-commander.readFile" />
57+
- To write content to a file: <tool name="desktop-commander.writeFile" />
58+
- To find symbol definitions: <tool name="lsmcp.definition" />
59+
- To create a GitHub pull request: <tool name="github.createPullRequest" />
60+
`;
61+
62+
// 3. Finally, Start the Agentic MCP Server
63+
// The mcpc function initializes the server and manages its tool dependencies.
64+
// We'll run it in "agentic" mode, which uses standard interactive tool calls.
65+
const server = mcpc(
66+
// Server metadata
67+
[{
68+
name: "codex-fork-agent",
69+
version: "0.1.0",
70+
}, {
71+
capabilities: { tools: {}, sampling: {} },
72+
}],
73+
// Agent definition
74+
[{
75+
name: "codex-fork-agent",
76+
options: {
77+
mode: "agentic", // or "sampling" for compatible clients
78+
},
79+
description,
80+
deps,
81+
}],
82+
);
83+
84+
// 4. Connect to a Transport to Make the Agent Accessible
85+
// For simplicity, we connect our server to the MCP stdio transport.
86+
const transport = new StdioServerTransport();
87+
await server.connect(transport);
88+
89+
console.log("✅ Codex Fork agent is running and connected via stdio.");
90+
```

‎docs/faq.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# FAQ
2+
3+
## Frequently Asked Questions
4+
5+
### Q1: What's the difference between "agentic" mode and "sampling" mode in MCPC?
6+
7+
**Agentic Mode (Default):** Works through standard, interactive calls where the
8+
LLM explicitly invokes each tool with distinct arguments. The agent makes
9+
deliberate tool calls step by step, allowing for full control and transparency
10+
of each action.
11+
12+
**Sampling Mode (Experimental):** Uses a client-side feature that leverages
13+
sampling to generate tool calls by requesting responses from the client's local
14+
LLM. This creates a "mini-agent" that operates inside the tool and requires a
15+
compatible client like VS Code Copilot. A single call to the agentic tool
16+
initiates an LLM request loop using the client's LLM.
17+
18+
### Q2: How do I reference existing MCP tools in my agent description?
19+
20+
You can reference MCP tools using XML-like syntax in your agent description:
21+
22+
```xml
23+
<tool name="server_name.tool_name" />
24+
<tool name="desktop-commander.exec" />
25+
<tool name="github.createPullRequest" />
26+
```
27+
28+
The `<tool>` tag supports advanced properties:
29+
30+
- **name**: Defines which tool to select from a dependent MCP server (syntax:
31+
`{mcp_server_name}.{tool_name}`)
32+
- **global**: (boolean, default false) When true, exposes tools in the MCP tools
33+
scope instead of keeping them internal
34+
- **hide**: (boolean, default false) Commonly used when overriding tools with
35+
custom properties or results
36+
37+
### Q3: What MCP transport types does MCPC support?
38+
39+
MCPC offers full support for all MCP transport protocols:
40+
41+
- **stdio**: Standard input/output transport (most common)
42+
- **sse**: Server-Sent Events transport
43+
- **streamable-http**: HTTP-based transport for web APIs
44+
45+
Example configurations:
46+
47+
```typescript
48+
const deps = {
49+
mcpServers: {
50+
"local-tool": {
51+
command: "npx",
52+
args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
53+
transportType: "stdio",
54+
},
55+
"web-api": {
56+
transportType: "streamable-http",
57+
url: "https://api.example.com/mcp/",
58+
headers: { "Authorization": "Bearer ${input:api_token}" },
59+
},
60+
},
61+
};
62+
```

‎docs/learn-more/achieving-agent-interoperability.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Achieving Agent Interoperability
2+
3+
By defining individual agents as agentic MCP tools, we create a framework where
4+
they can cooperate, orchestrated by an LLM. This approach enables true agent
5+
interoperability, much like an Agent-to-Agent (A2A) communication protocol.
6+
7+
This is achieved through two key mechanisms:
8+
9+
- **Dynamic Capability Discovery:** An LLM can dynamically discover the
10+
capabilities of each agent. Because every agent is exposed as a standard MCP
11+
tool, its functions are described as tool definitions and passed to the
12+
controlling LLM with each request. This allows for a dynamic, on-the-fly
13+
integration of different agents.
14+
- **LLM-Mediated Collaboration:** Collaboration between agents is mediated by
15+
the LLM. One agent can invoke another by making a standard tool call through
16+
the LLM. The LLM then routes the request to the appropriate agent tool,
17+
collects the result, and returns it as feedback. This creates a seamless
18+
workflow where multiple specialized agents can work together to solve complex
19+
problems.

‎docs/learn-more/agentic-mcp-tools.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Agentic MCP Tools
2+
3+
# What is an Agentic MCP tool
4+
5+
An Agentic MCP tool is a tool that acts like an agent, designed to complete
6+
complex tasks by calling dependent MCP tools within a multi-step loop.
7+
8+
# How it works
9+
10+
While a normal agent calls an LLM in a loop for each step (e.g., for reasoning
11+
or tool calls), an Agentic MCP tool is primarily a tool whose behavior depends
12+
on the selected mode.
13+
14+
**Agentic Mode:** The LLM interactively generates tool calls for the agentic
15+
tool. It provides different arguments to call various dependent MCP tools,
16+
allowing it to complete the overall agent task.
17+
18+
**Sampling Mode:** A single call to the agentic tool initiates an LLM request
19+
loop using the client's LLM. This process calls dependent MCP tools in each
20+
step, creating a "mini-agent" that operates inside the tool.

‎docs/quickstart/ai-sdk-integration.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# AI SDK Integration

0 commit comments

Comments
 (0)