a8fa159f0f
- 新增 aio-mcp 项目框架 - 新增 .trae/skills/ OCR/SKU 设计工具 - 更新 auto-check 配置和 stress 包 - 删除 fnhelp 文档目录 - 更新 Docker 压力测试脚本
101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
# aio-mcp
|
||
|
||
aio-system 的自定义 MCP 服务器（Go）。作为 AI Agent 的「手」，以 MCP 协议对外暴露工具；后续的 SQLite / 文件 / 打印 / 检测等自定义工具都往这里加。
|
||
|
||
基于官方 SDK：[github.com/modelcontextprotocol/go-sdk](https://github.com/modelcontextprotocol/go-sdk)（v1.7.0）。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
aio-mcp/
|
||
├── main.go # 入口：选择 stdio / http 传输
|
||
└── internal/
|
||
├── server/
|
||
│ └── server.go # 服务器装配（创建实例 + 注册工具）
|
||
└── tools/
|
||
├── registry.go # 工具注册总表 RegisterAll
|
||
├── ping.go # 示例工具：健康检查（无参数）
|
||
└── echo.go # 示例工具：参数传递（有参数）
|
||
```
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
go build -o aio-mcp.exe . # 构建
|
||
|
||
# stdio 模式（默认，供本地 Agent 拉起，如 Reasonix / Claude）
|
||
aio-mcp.exe
|
||
|
||
# http 模式（远程客户端访问）
|
||
aio-mcp.exe -transport http -addr localhost:8000
|
||
```
|
||
|
||
依赖拉取走内网代理，若需直连官方源：`go env -w GOPROXY=https://proxy.golang.org,direct`。
|
||
|
||
## 新增一个工具
|
||
|
||
1. 在 `internal/tools/` 新建文件（如 `weather.go`），用参数 struct + 泛型 `mcp.AddTool` 注册：
|
||
|
||
```go
|
||
package tools
|
||
|
||
import (
|
||
"context"
|
||
"github.com/modelcontextprotocol/go-sdk/mcp"
|
||
)
|
||
|
||
type weatherArgs struct {
|
||
City string `json:"city" jsonschema:"城市名，必填"`
|
||
Days int `json:"days,omitempty" jsonschema:"预报天数，默认 1"`
|
||
}
|
||
|
||
func registerWeather(s *mcp.Server) {
|
||
mcp.AddTool(s, &mcp.Tool{
|
||
Name: "weather",
|
||
Description: "查询某城市未来几天的天气。",
|
||
}, func(_ context.Context, _ *mcp.CallToolRequest, args weatherArgs) (*mcp.CallToolResult, any, error) {
|
||
// ...业务逻辑...
|
||
return &mcp.CallToolResult{
|
||
Content: []mcp.Content{&mcp.TextContent{Text: "晴，25℃"}},
|
||
}, nil, nil
|
||
})
|
||
}
|
||
```
|
||
|
||
2. 在 `internal/tools/registry.go` 的 `RegisterAll` 中追加一行：`registerWeather(s)`。
|
||
|
||
工具需要共享状态（SQLite 连接等）时，参考 `registry.go` 顶部注释，把 `RegisterAll` 演进为带 `deps` 参数。
|
||
|
||
## 冒烟测试
|
||
|
||
stdio 模式用换行分隔的 JSON-RPC 直接喂协议消息：
|
||
|
||
```bash
|
||
printf '%s\n' \
|
||
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}' \
|
||
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
|
||
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
|
||
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo","arguments":{"message":"你好","times":2}}}' \
|
||
| aio-mcp.exe
|
||
```
|
||
|
||
http 模式：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/mcp -H "Content-Type: application/json" \
|
||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0.0.1"}}}'
|
||
```
|
||
|
||
## 接入 Agent（以 Reasonix / Claude 为例）
|
||
|
||
在客户端 MCP 配置中注册，指向构建产物：
|
||
|
||
```json
|
||
{ "mcpServers": { "aio-mcp": { "command": "D:\\workspace\\membank\\aio-mcp\\aio-mcp.exe" } } }
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- stdio 模式下 **stdout 是协议通道**：日志已固定输出到 stderr，业务代码请勿往 stdout 打印。
|
||
- 工具名只允许 `a-z A-Z 0-9 _ - .`。
|