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

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

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.
    -