🔌 MCP 协议深度解析

// 1. Host 向 Server 发送工具调用请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_stock_price",
    "arguments": { "symbol": "600519" }
  }
}

// 2. Server 返回结果
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "贵州茅台(600519): ¥1,680.00 (+2.3%)" }]
  }
}

# ~/.hermes/config.yaml
mcp_servers:

  # GitHub：需要 Personal Access Token
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

  # PostgreSQL：连接字符串
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres",
           "postgresql://user:pass@localhost/mydb"]

  # 文件系统：限制访问目录
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem",
           "/home/user/documents"]   # 只允许访问此目录

// stock-mcp-server/src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "stock-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 声明工具列表（模型会看到这些定义）
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "get_stock_price",
    description: "查询A股实时行情，输入股票代码返回最新价格和涨跌幅",
    inputSchema: {
      type: "object",
      properties: {
        symbol: { type: "string", description: "股票代码，如 600519" }
      },
      required: ["symbol"]
    }
  }]
}));

// 处理工具调用
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_stock_price") {
    const { symbol } = request.params.arguments as { symbol: string };
    // 调用行情 API（示例）
    const price = await fetchStockPrice(symbol);
    return {
      content: [{ type: "text", text: `${symbol}: ¥${price.current} (${price.change}%)` }]
    };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

// 启动 stdio 传输
const transport = new StdioServerTransport();
await server.connect(transport);

# stock_mcp_server.py
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

app = Server("stock-server")

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_stock_price",
            description="查询A股实时行情",
            inputSchema={
                "type": "object",
                "properties": {
                    "symbol": {"type": "string", "description": "股票代码"}
                },
                "required": ["symbol"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_stock_price":
        symbol = arguments["symbol"]
        price = await fetch_stock_price(symbol)  # 你的行情获取逻辑
        return [TextContent(type="text", text=f"{symbol}: ¥{price}")]

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, app.create_initialization_options())

# ~/.hermes/config.yaml
mcp_servers:
  stock:
    command: node
    args: ["/path/to/stock-mcp-server/dist/index.js"]
    # Python 版本：
    # command: python3
    # args: ["/path/to/stock_mcp_server.py"]

npx @modelcontextprotocol/inspector node dist/index.js
# 打开 http://localhost:5173 进行可视化调试