Skip to main content
Glama
liuyuyan6100

mcp-server-demo

by liuyuyan6100
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

MCP Server 开发指南

项目结构

mcp-server-demo/
├── server_fastmcp.py   # FastMCP 方式（推荐，简洁）
├── server_raw.py        # 原生 SDK 方式（底层，灵活）
├── test_server.py       # 测试脚本
└── README.md            # 本文件

Related MCP server: FastMCP Demo Server

快速开始

# 1. 初始化环境（创建 venv + 安装依赖）
bash setup.sh

# 2. 运行测试
.venv/bin/python test_server.py          # 测试 FastMCP 版本
.venv/bin/python test_server.py raw      # 测试原生 SDK 版本

# 或者先激活 venv，之后直接用 python
source .venv/bin/activate
python test_server.py

两种开发方式对比

FastMCP（推荐入门）

  • 用装饰器 @mcp.tool() 自动从函数签名生成 JSON Schema

  • 参数类型从 type hints 自动推断

  • docstring 自动变成工具描述

  • 启动一行代码：mcp.run()

原生 SDK（底层）

  • 手动定义 inputSchema（JSON Schema 格式）

  • 手动实现 list_tools() 和 call_tool() 两个处理函数

  • 更接近协议本身，适合需要精细控制的场景

如何接入 Hermes

在 ~/.hermes/config.yaml 中添加：

mcp_servers:
  demo:
    command: "/home/ubuntu/mcp-server-demo/.venv/bin/python"
    args: ["/home/ubuntu/mcp-server-demo/server_fastmcp.py"]

重启 Hermes 后，会自动发现并注册两个工具：

  • mcp_demo_calculate — 计算数学表达式

  • mcp_demo_get_weather — 查询天气

MCP 协议通信流程

客户端 (Hermes)                    Server (你的代码)
    |                                  |
    |-- initialize 请求 ------------->|
    |<-- initialize 响应 -------------|   (serverInfo, capabilities)
    |                                  |
    |-- tools/list 请求 ------------->|
    |<-- tools/list 响应 -------------|   (工具名称 + inputSchema)
    |                                  |
    |-- tools/call 请求 ------------->|
    |   (name + arguments)             |
    |<-- tools/call 响应 -------------|   (TextContent 结果)
    |                                  |

核心概念

Tool 定义

每个工具需要：

  • name: 唯一名称

  • description: 描述（LLM 会读这个来决定什么时候用）

  • inputSchema: JSON Schema 格式的参数定义

传输方式

  • stdio: 通过 stdin/stdout 通信，Hermes 默认用这个

  • HTTP/StreamableHTTP: 监听端口，适合远程调用

安全注意事项

  • 不要在 tool 实现里做危险操作（直接执行用户输入的代码等）

  • 使用参数校验（FastMCP 的 type hints 会自动校验）

  • 敏感信息通过 env 配置传入，不要硬编码

进阶话题

  • Resources: 暴露可读取的数据源（文件、数据库等）

  • Prompts: 预定义的提示词模板

  • Sampling: Server 主动请求 LLM 做推理（需要客户端支持）

  • 错误处理: 返回 isError: true 的结果

  • 进度通知: 长时间运行的工具可以发送进度更新

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • FastMCP Tools Calculator

    sriharsha-inthub
    F
    license
    Not graded
    quality
    D
    maintenance
    A demonstration MCP server that provides calculator functionality through both stdio and FastAPI implementations. Enables users to perform mathematical calculations via MCP tools using the FastMCP framework.
    -

  • FastMCP Basic Server

    sharmaratnesh
    F
    license
    Not graded
    quality
    C
    maintenance
    A basic MCP server implementation using the FastMCP framework that provides utility tools for greetings and mathematical calculations. It is designed to demonstrate tool integration for AI-assisted development workflows like Cline.
    -