为了便于您复制，我已经包装了整个更新 README.md 单个Markdown代码块中的内容。
我还整合了 viztracer 指令是开发工作流程的核心部分。
# MCP Server — Python
A production-ready Model Context Protocol server built with Python, FastMCP, Pydantic v2, and Docker.
## Quick start
1. Clone and enter the project
git clone && 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`**.
1. 等待消息 `Saving trace data to disk...`.
1. 打开基于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 /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` 使用纯异步逻辑。
1. 创建 `src/mcp_server/handlers/tools/my_tool.py` 带着一个 `register(mcp)` 功能。
1. 导入和调用 `my_tool.register(mcp)` 在 `server.py`.
1. 在中编写测试 `tests/unit/test_my_service.py`.