Skip to main content
Glama
demo-mcp-server

demo-mcp-server

by ZureJack

demo-mcp-server

一个使用 Python 编写的 Model Context Protocol (MCP) Server, 可直接接入 Cline / Claude Desktop 等 MCP 客户端。

设计要点

  • 始终在虚拟环境中运行:run.sh 自动创建 .venv、安装依赖,Cline 配置只需一行 command。

  • 主框架与能力解耦:server.py 只负责启动与装配;所有业务工具 / 资源 / 提示位于 tools/ 包内,新增能力无需改动任何现有文件。

  • 能力自注册:每个能力子包通过 __register__.py 自我注册,无需手动维护模块清单。

  • 按需依赖:每个能力子包维护自己的 requirements.txt,不使用的模块无需安装其依赖。

Related MCP server: Remote MCP Server

环境要求

  • Python 3.10+

  • Linux / macOS(run.sh 为 Bash 脚本;Windows 见下方说明)

快速开始

方式一:run.sh(推荐)

git clone git@github.com:ZureJack/demo-mcp-server.git
cd demo-mcp-server
./run.sh

首次运行自动创建 .venv/ 并安装核心依赖;再次启动直接进入 server。

方式二:pip install

pip install .
demo-mcp-server     # 启动 server

安装后可以直接在任意目录通过 demo-mcp-server 命令启动(无需 run.sh)。

可视化调试

source .venv/bin/activate
mcp dev server.py

内置能力

模块

说明

文档

basic

回显、系统信息

README

math_tools

算术运算

README

time_tools

当前时间(支持时区)

README

file_tools

读取文本文件

README

resources

MCP Resources(greeting)

README

prompts

MCP Prompts(summarize)

README

install_deps

按需安装模块依赖

README

c_identifier_find

查找 C 标识符定义与声明

README

在 Cline 中接入

在 cline_mcp_settings.json 中加入:

{
  "mcpServers": {
    "demo-mcp-server": {
      "command": "/home/loto/work/mcp/run.sh"
    }
  }
}

配置文件位置:

  • VS Code (Linux):~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

  • VS Code (macOS):~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

  • VS Code (Windows):%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

Windows 用户

通过 WSL 调用:

{
  "mcpServers": {
    "demo-mcp-server": {
      "command": "wsl",
      "args": ["/home/loto/work/mcp/run.sh"]
    }
  }
}

添加新能力

得益于"主框架/能力"分离的设计,新增能力只需在 tools/ 下新建一个子包, 无需修改任何现有文件。

子包结构

一个能力子包由 3 个文件组成:

tools/weather/               # 子包目录名即为能力名
├── __init__.py              # 能力实现:注册工具/资源/提示
├── __register__.py          # 自注册入口(一行代码)
└── requirements.txt         # (可选)本模块的外部依赖

各文件说明

__init__.py

能力实现文件。必须暴露一个 register(mcp) 函数,在此函数内通过装饰器注册工具/资源/提示。

"""天气查询能力。"""          # 模块文档字符串

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mcp.server.fastmcp import FastMCP


def register(mcp: "FastMCP") -> None:
    @mcp.tool()
    def fetch_weather(city: str) -> dict:
        """根据城市名查询天气。"""
        # ... 你的实现 ...
        return {"city": city, "temp": 25}

约定:

  • 不要在模块顶层引用全局 mcp,保证模块与主框架解耦,便于独立导入和单元测试。

  • 可以同时注册多个 tool/resource/prompt。

  • 工具的参数类型注解会被 MCP SDK 自动转为 JSON Schema,客户端(如 Cline)会据此生成参数填写界面。

__register__.py

自注册入口。register_all() 会通过子进程执行此文件,将模块名写入 .registry.json。

from lib.registry import register_module

register_module("weather")

仅此两行,不可省略。这个步骤让主框架知道存在这个能力模块。

requirements.txt(可选)

该模块的外部 Python 依赖,每行一个包名(标准 pip 格式):

requests>=2.31.0
beautifulsoup4>=4.12.0

如果模块只使用 Python 标准库,此文件可以留空(或写注释说明无依赖)。

安装方式:

python tools/install_deps/install-deps.py           # 安装所有模块的依赖
python tools/install_deps/install-deps.py weather   # 只安装指定模块的依赖

AI agent 也可以直接调用 install_deps_for_modules 工具在线安装。

注册与生效

保存文件后,Cline 会自动发现变更并重启 MCP server。重启后即可看到新的工具——server.py 和 tools/__init__.py 都不需要修改。

如果想手动刷新注册信息(一般情况下不需要),可以在项目根目录执行:

PYTHONPATH=. python -c "
import tools
from mcp.server.fastmcp import FastMCP
mcp = FastMCP('test')
tools.register_all(mcp)
print('已注册模块:', tools.TOOL_MODULES)
"

常见问题

Q1. ./run.sh: Permission denied

chmod +x run.sh

Q2. ModuleNotFoundError: No module named 'mcp' 删除 .venv 重新运行 ./run.sh 即可。

Q3. server 启动后没有任何输出 正常行为:stdio 传输下 stdout 只用于 JSON-RPC,日志在 stderr。

Q4. 想强制使用别的 Python 版本创建 venv

PYTHON_BIN=/usr/bin/python3.12 ./run.sh

参考

Available Tools

6 tools
addA

计算两个数之和。

Inputs: a (required), b (required). Returns: result

calculateA

对一个简单的算术表达式求值。

仅允许数字、空白以及 + - * / ( ) . % 运算符, 禁止任何变量、函数或属性访问,以避免代码注入。

Args: expression: 例如 "1 + 2 * (3 - 4)"。

Returns: 表达式的字符串化结果。

Inputs: expression (required). Returns: result

echoA

回显输入文本,可用于测试 server 是否连通。

Args: text: 要回显的文本。

Returns: 与输入完全一致的字符串。

Inputs: text (required). Returns: result

get_current_timeA

获取当前时间。

Args: tz: 可选 IANA 时区名(例如 "Asia/Shanghai", "UTC", "America/New_York")。未提供时使用系统本地时区。

Returns: ISO-8601 格式的时间字符串。

Inputs: tz. Returns: result

read_text_fileA

读取一个本地文本文件的内容。

Args: path: 文件的绝对路径或相对于 server 启动目录的相对路径。 max_bytes: 最多读取的字节数,防止把超大文件喂给 LLM,默认 64KB。

Returns: 文件文本内容(UTF-8 解码,非法字节会被替换)。

Inputs: path (required), max_bytes. Returns: result

system_infoA

返回当前运行 server 的系统与解释器信息。

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have distinctly different purposes, but add and calculate both perform arithmetic, which could cause confusion. Descriptions help differentiate (add handles two numbers, calculate evaluates expressions), but the overlap is notable.

    Naming Consistency3/5

    Tool names use lowercase with underscores for multi-word names, but the pattern is inconsistent: add, calculate, and echo are single verbs, while get_current_time and read_text_file follow verb_noun. This lack of uniformity reduces predictability.

    Tool Count5/5

    With 6 tools, the server is well-scoped for a demo utility set. Each tool serves a clear role without being overwhelming or too sparse.

    Completeness4/5

    The tools cover common utility tasks like arithmetic, echoing, time retrieval, file reading, and system info. While it lacks some common utilities (e.g., string manipulation, random generation), it is adequate for a demo server with only minor gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Python-based MCP server demonstrating basic math and text tools, supporting both SSE and STDIO transports for integration with AI assistants like Cline in VS Code.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      A Python-based MCP server that provides mathematical tools like addition and random number generation, plus server metadata.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A minimal MCP server providing basic tools for arithmetic, text echoing, and timezone-aware current time retrieval.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A simple MCP server that provides basic utility tools for text manipulation, file operations, and calculations, intended to be connected to Claude AI desktop app.
      -