AI导哈

模型上下文协议服务器

一个基于Python、FastMCP、Pydantic v2和Docker构建的生产级模型上下文协议服务器，支持搜索、计算、文件资源和提示处理等功能。

  • by Oussama-nasri
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Oussama-nasri/ouss_mcp

使用说明

为了便于您复制，我已经包装了整个更新 README.md 单个Markdown代码块中的内容。

我还整合了 viztracer 指令是开发工作流程的核心部分。

# MCP Server — Python

A production-ready Model Context Protocol server built with Python, FastMCP, Pydantic v2, and Docker.

## Quick start

```bash
# 1. Clone and enter the project
git clone [https://github.com/Oussama-nasri/ouss_mcp](https://github.com/Oussama-nasri/ouss_mcp) && cd ouss_mcp

# 2. Copy and fill in your environment variables
cp .env.example .env
# Edit .env — at minimum set API_KEY to a 32+ char random string:
#   python -c "import secrets; print(secrets.token_hex(32))"

# 3. Install dependencies (requires uv)
pip install uv && uv sync

# 4. Run in stdio mode (for Claude Desktop)
python -m mcp_server.server

# 5. Run in SSE mode (for remote access)
TRANSPORT=sse python -m mcp_server.server

项目结构

src/mcp_server/
├── server.py               Entry point, server bootstrap
├── config.py               Typed settings via pydantic-settings
├── handlers/
│   ├── tools/
│   │   ├── search.py       search tool
│   │   └── calculator.py   calculate tool
│   ├── resources/
│   │   └── file_resource.py   file:// URI handler
│   └── prompts/
│       └── summarize_prompt.py   summarize + code_review prompts
├── middleware/
│   ├── auth.py             Constant-time API key verification
│   ├── rate_limiter.py     Sliding window rate limiter (in-process + Redis)
│   └── logging.py          Structured JSON logging via structlog
├── services/
│   ├── search_service.py   Search logic (swap for real backend)
│   └── calculator_service.py   AST-based safe math evaluator
└── utils/
    └── resilience.py       Retry + backoff helpers (tenacity)

可用工具

工具 说明
search 搜索知识库。Args： query （str）， limit （int，默认值10）
calculate 安全地计算数学表达式。Args： expression （str）

可用资源

URI 描述
file:// 列出文件根目录中的所有文件
file://{path} 读取特定文件（仅限UTF-8文本，最大10 MB）

可用提示

提示 描述
summarize 结构化摘要。Args： text, style （项目符号/段落/tldr）， language, max_words
code_review 代码审查。Args： code, language, focus （安全/性能/风格/全部）

运行测试

uv run pytest                          # all tests
uv run pytest tests/unit/              # unit tests only
uv run pytest tests/integration/       # integration tests only
uv run pytest --cov=src               # with coverage

跟踪和性能可视化

使用 viztracer 调试延迟并可视化MCP处理程序和异步任务的执行流。

1.生成跟踪

使用以下命令通过跟踪器运行服务器 --log_async 标记以正确捕获事件循环：

# Start the server with tracing enabled
viztracer --log_async -o mcp_trace.json start_mcp.py

2.执行工作量

当服务器运行时，在单独的终端中执行测试客户端或自动测试：

python src/mcp_client/test_mcp.py

3.保存和查看

  1. 返回服务器终端并按 Ctrl+C.
  2. 等待消息 Saving trace data to disk....
  3. 打开基于Chrome的交互式查看器：
vizviewer mcp_trace.json

导航提示： 使用 W/S 为了放大/缩小， A/D 向左/向右移动，以及 F 缩放以适应整个轨迹。

Docker部署

# Build and start all services
cd docker
docker compose up -d

# View logs
docker compose logs -f mcp

# Stop
docker compose down

VPS设置（一次性）

# On your VPS
sudo apt update && sudo apt install -y docker.io docker-compose-plugin nginx certbot python3-certbot-nginx

# Clone the repo
sudo git clone [https://github.com/Oussama-nasri/ouss_mcp](https://github.com/Oussama-nasri/ouss_mcp) /opt/ouss_server
sudo cp /opt/mcp-server/.env.example /opt/mcp-server/.env
# Fill in /opt/mcp-server/.env

# Install systemd service
sudo cp /opt/mcp-server/docker/mcp-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-server

# Set up Nginx + TLS
sudo cp /opt/mcp-server/docker/nginx.conf /etc/nginx/sites-available/mcp-server
sudo ln -s /etc/nginx/sites-available/mcp-server /etc/nginx/sites-enabled/
# Edit the server_name in nginx.conf, then:
sudo certbot --nginx -d mcp.yourdomain.com
sudo systemctl reload nginx

环境变量

变量 必填 默认 描述
API_KEY 是 -- 32+字符密钥
TRANSPORT 没有 stdio stdio 或 sse
HOST 没有 0.0.0.0 绑定地址
PORT 没有 3000 绑定端口
LOG_LEVEL 没有 INFO DEBUG/INFO/WARNING/ERROR
DATABASE_URL 没有 "" Postgres异步URL
REDIS_URL 没有 redis://localhost:6379 重定向URL
RATE_LIMIT_PER_MINUTE 没有 100 每分钟请求数
FILE_ROOT 没有 /data/files 文件的根目录：//资源

添加新工具

  1. 创建 src/mcp_server/services/my_service.py 使用纯异步逻辑。
  2. 创建 src/mcp_server/handlers/tools/my_tool.py 带着一个 register(mcp) 功能。
  3. 导入和调用 my_tool.register(mcp) 在 server.py.
  4. 在中编写测试 tests/unit/test_my_service.py.

相关 MCP