What can you do with this server?

This is a Python-based MCP (Model Context Protocol) server providing utility tools for testing connectivity, system inspection, file operations, arithmetic, and time retrieval. * Echo: Reflects back any input text — useful for testing server connectivity. * System Info: Returns OS and Python interpreter details. * Read Text File: Reads a local text file by path, with a configurable byte limit (default 64KB) to avoid overloading the LLM. * Add: Computes the sum of two numbers. * Calculate: Safely evaluates simple arithmetic expressions (e.g., 1 + 2 * (3 - 4)), supporting + - * / ( ) . % without allowing variables or function calls. * Get Current Time: Returns the current time in ISO-8601 format, with optional IANA timezone support (e.g., UTC, America/New_York). The server also supports MCP Resources (e.g., a greeting resource), MCP Prompts (e.g., a summarize prompt), on-demand Python dependency installation, and tools for finding C identifier definitions and declarations.

How do I use demo-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@demo-mcp-server what time is it in Tokyo?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

demo-mcp-server

by ZureJack

Overview Schema Source Related Servers Score Discussions Admin

Python

Local

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

计算两个数之和。

ParametersJSON Schema

Name	Required	Description	Default
`a`	Yes
`b`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, description only states sum calculation. No additional behavioral context (e.g., precision, overflow). Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. Front-loaded with essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple addition tool with output schema and no nested objects, the description is sufficient. No missing critical information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but description only mentions sum of two numbers without explaining parameters 'a' and 'b' beyond their names. Minimal added value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'calculate' and the resource 'sum of two numbers', which is specific and distinguishes from sibling tools like 'echo' or 'get_current_time'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives like 'calculate'. Usage is implied for simple addition, but lacks context for when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

calculateA

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

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

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

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

ParametersJSON Schema

Name	Required	Description	Default
`expression`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the safety restrictions (preventing code injection) and the return type (stringified result), which is sufficient for a simple arithmetic evaluator.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: a few sentences covering purpose, constraints, and parameter description with an example. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main functionality and parameter, but lacks information on error handling (e.g., invalid expressions, division by zero). However, given the simplicity and presence of an output schema, it is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates by explaining the 'expression' parameter as an arithmetic expression with an example, adding meaning beyond the schema's type definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool evaluates simple arithmetic expressions, lists allowed operators, and prohibits variables/functions to prevent injection. It distinguishes itself from sibling tools like add, echo, and system_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies constraints (only allowed operators, no variables/functions) but does not explicitly state when to use this tool versus alternatives or provide prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

echoA

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

Args: text: 要回显的文本。

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

ParametersJSON Schema

Name	Required	Description	Default
`text`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It transparently states that the tool returns the exact input string, with no hidden side effects or behaviors. It is straightforward and sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with a single-sentence purpose followed by brief parameter and return explanations. It is well-structured and front-loaded, with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one parameter, clear return), the description fully covers purpose, parameter, and output. It is complete and requires no additional information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameter descriptions (0% coverage). The description explains that 'text' is the text to echo, adding essential meaning beyond the schema. It is clear but could include more detail like format or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool echoes input text and can be used to test server connectivity. It distinguishes itself from sibling tools (add, calculate, etc.) by specifying its unique function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear use case (testing server connectivity) but does not explicitly mention when not to use it or alternatives. It implies appropriate contexts for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_current_timeA

获取当前时间。

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

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

ParametersJSON Schema

Name	Required	Description	Default
`tz`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden for behavioral disclosure. It states the output format (ISO-8601) but does not explicitly mention that the tool is read-only or has no side effects, which is assumed but not stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with clear sections for Args and Returns. It is front-loaded with the purpose and contains no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and an output schema, the description is complete. It covers the parameter, return format, and default behavior adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It fully explains the 'tz' parameter: IANA timezone name, examples, and default behavior (system local time). This adds significant value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get current time' (获取当前时间), specifying the exact action and resource. It is distinct from sibling tools like add, calculate, or read_text_file, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the optional tz parameter and its default behavior, but does not provide explicit guidance on when to use this tool versus alternatives or when not to use it. The usage context is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_text_fileA

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

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

Returns: 文件文本内容（UTF-8 解码，非法字节会被替换）。

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`max_bytes`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

未提供注解，但描述说明了UTF-8解码、非法字节替换、max_bytes限制，行为透明。未提及错误处理或权限，但复杂度较低。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

三句话，结构清晰，参数列表分明，无冗余信息。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

有输出schema，描述覆盖返回值（UTF-8文本），参数少且简单，内容完整。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

schema覆盖率为0%，但描述为path和max_bytes提供了有意义的信息（绝对/相对路径、默认64KB），比schema仅提供类型和标题更有用。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

描述明确指定了'读取本地文本文件内容'，动词+资源清晰，且与兄弟工具（算术、时间等）明显区分。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

虽然未明确说明何时不使用，但兄弟工具功能差异极大，隐式使用场景清晰。默认max_bytes防止超大文档提供了上下文。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

system_infoA

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It states the output type (system/interpreter info) but lacks details on side effects, safety, or response format. Since the tool has no parameters and is read-like, it's adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the purpose without any superfluous words. It is well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no annotations, no output schema), the description is largely sufficient. However, it could mention the return format (e.g., JSON object) to help the agent process the output, but the current level is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%, so the description does not need to add parameter info. Baseline 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool returns system and interpreter information of the server, using a clear verb and resource. It distinguishes well from sibling tools (add, calculate, etc.) that serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when system/interpreter info is needed, and sibling tools cover distinct operations (arithmetic, time, file reading). No explicit when-not or alternatives, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

6 tool updatesv0.1.0Jun 27, 2026
- First observedadd
- First observedcalculate
- First observedecho
- First observedget_current_time
- First observedread_text_file
- First observedsystem_info

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Scored 2026-06-27 09:16 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

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

smithery-ai-cookbook-python-quickstart
ai.smithery
A simple MCP server built with FastMCP and python
Developer Tools
213
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
mcp A
tools.clean
Read-only developer, date, finance, and text utilities. Authless remote MCP server by Clean.tools.
Developer Tools Finance
422
Second server!
com.fenetresurciel.verylongmcp
A non functional MCP server (yet)
Developer Tools
2

Related MCP Servers

Python FastMCP Server
Code Execution Command Line
rajeshsahu09
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.
Updated 5 months ago (2026-04-23 15:48 UTC)
-
Remote MCP Server
Developer Tools
Pavankurapati03
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.
Updated 3 months ago (2026-06-08 16:12 UTC)
-
simple-mcp
Developer Tools
hareramray
F
license
Not graded
quality
D
maintenance
A minimal MCP server providing basic tools for arithmetic, text echoing, and timezone-aware current time retrieval.
Updated 3 months ago (2026-06-20 17:44 UTC)
-
Simple MCP Server
File Systems Developer Tools
eshvargb
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.
Updated 10 months ago (2025-10-29 05:39 UTC)
-

demo-mcp-server

设计要点

环境要求

快速开始

方式一：run.sh（推荐）

方式二：pip install

可视化调试

内置能力

在 Cline 中接入

Windows 用户

添加新能力

子包结构

各文件说明

__init__.py

__register__.py

requirements.txt（可选）

注册与生效

常见问题

参考

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

`init.py`

`register.py`

`requirements.txt`（可选）