mcp-builder

Files (2)

• SKILL.md
• example-openrouter-perplexity.md · references/

SKILL.md (first lines)

# MCP Builder

Build and register MCP (Model Context Protocol) servers for OctoAgent.

## When to Use

- Creating a new MCP server to integrate an external API or service
- Scaffolding an MCP server project (Node.js or Python)
- Adding tools or resources to an existing MCP server
- Registering a locally built MCP server with OctoAgent
- Debugging MCP server startup or tool discovery issues

## When NOT to Use

- Using already-registered MCP tools -> they're auto-available, just call them
- Simple REST API calls -> use `web.fetch` directly
- Non-MCP integrations -> use regular Pydantic Skills instead

## MCP Overview

MCP servers expose **tools** and **resources** over stdio transport. OctoAgent discovers and registers them as `mcp.{server}.{tool}` in the ToolBroker.

```
OctoAgent ToolBroker
  └── McpRegistryService
        └── stdio_client(command, args, env)
              └── MCP Server process (Node.js / Python)
                    ├── tool: web_search
                    ├── tool: create_issue
                    └── resource: config://settings
```

## Scaffolding a New MCP Server

### Option A: Node.js (推荐，启动快)

```bash
mkdir -p ~/.octoagent/mcp-servers/<server-name>
cd ~/.octoagent/mcp-servers/<server-name>

cat > package.json << 'EOF'
{
  "name": "<server-name>-mcp",
  "version": "1.0.0",
  "type": "module",
  "main": "server.js",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.21.1"
  }
}
EOF

npm install
```

Minimal `server.js`:

```javascript
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "<server-name>",
  version: "1.0.0",
});

// 注册工具
server.tool(
  "tool_name",
  "工具描述：做什么、什么场景用",
  {
    param1: z.string().describe("参数说明"),
    param2: z.number().optional().describe("可选参数"),
  },
  async ({ param1, param2 }) => {
    // 实现逻辑
    const result = `处理: ${param1}`;
    return {
      content: [{ type: "text", text: result }],
    };
  }
);

// 启动
const transport = new StdioServerTransport();
await server.connect(transport);
```

### Option B: Python (适合调用 Python 生态库)

```bash
mkdir -p ~/.octoagent/mcp-servers/<server-name>
cd ~/.octoagent/mcp-servers/<server-name>

python3 -m venv .venv
source .venv/bin/activate
pip install mcp
```

Minimal `server.py`:

```python
#!/usr/bin/env python3
"""<server-name> MCP Server"""
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("<server-name>")

@mcp.tool()
async def tool_name(param1: str, param2: int = 0) -> str:
    """工具描述：做什么、什么场景用"""
    return f"处理: {param1}, {param2}"

if __name__ == "__main__":
    mcp.run(transport="stdio")
```

From connor-git-yaml/OctoAgent, MIT.

More from connor-git-yaml/OctoAgent