MCP 服务器

mcp-personal

A personal MCP server built with Python FastMCP, offering tools for paper retrieval, dataset analysis, project scaffolding, and directory utilities, with stdio and HTTP transport plus optional bearer token authentication.

README

mcp-personal · 个人 MCP 服务器

用 Python（FastMCP）构建的个人 MCP 服务器，可接入 Cursor / VS Code / DeepSeek Harness 等任意 MCP 客户端。

完整规划见 PLAN.md · 展示素材见 docs/展示指南.md · 当前进度：四大场景 + HTTP + 鉴权 + pdf_extract ✅ · 21 个测试通过 · 环境变量见 .env.example

快速开始

# 1. 创建虚拟环境并安装（需 Python 3.11+ 或 uv）
uv venv
uv pip install -e ".[dev]"

# 2. 跑测试
uv run pytest tests -q

# 3. 启动服务器（stdio，供客户端接入）
uv run python -m mcp_personal

# 4. 冒烟测试：真实 stdio 子进程链路
uv run python scripts/smoke_stdio.py

# 5. 查看服务器注册的能力清单（Tools/Prompts/Resources）
uv run python scripts/verify_capabilities.py

# 6. 调试：官方 MCP Inspector
uv run mcp dev src/mcp_personal/server.py

接入客户端

配置已预置（portable 写法：uv run --project . 自动定位环境，仓库可任意移动）：

客户端	配置文件
Cursor	`.cursor/mcp.json`（设置 → MCP → 添加本地服务器）
VS Code	`.vscode/mcp.json`（需安装 "MCP" 扩展 / Copilot Chat）
其他	标准 stdio 配置：`command + args` 同上

接入后先让 AI 调用 ping 工具验证链路。

HTTP 远程接入（可选）

# 终端 1：启动 HTTP 服务（默认 127.0.0.1:8000，--host 0.0.0.0 可局域网访问）
uv run python scripts/run_http.py --port 8000

# 终端 2：用官方客户端验证链路
uv run python scripts/client_http_check.py --url http://127.0.0.1:8000/mcp

其他远程客户端把 MCP 服务器地址配成 http://<host>:<port>/mcp 即可。

HTTP 鉴权（可选）

设置环境变量后启动，所有请求需携带 Authorization: Bearer <token>：

# 终端 1：带鉴权启动
MCP_API_TOKEN=my-secret uv run python scripts/run_http.py --port 8000

# 终端 2：带 token 验证
uv run python scripts/client_http_check.py --url http://127.0.0.1:8000/mcp --token my-secret

说明：基于 FastMCP 官方 StaticTokenVerifier（API key 风格），token 明文存储，仅适合个人/开发用途；生产应改用 OAuth/JWT。

目录结构

├── PLAN.md            # 项目规划书
├── pyproject.toml     # 依赖与打包
├── src/mcp_personal/  # 服务器代码
│   ├── server.py      # FastMCP 入口（注册全部原语）
│   ├── tools/         # Tool：paper(检索)/dataset(摸底)/scaffold(课设)/devtools(目录树)
│   ├── prompts.py     # Prompt：literature_review 文献综述框架
│   └── resources.py   # Resource：papers://list 本地论文库
├── papers/            # 本地论文库（放 PDF）
├── datasets/          # 竞赛数据集（dataset_info 工具使用）
├── tests/             # pytest 测试（13 个）
├── .github/workflows/ # CI：push/PR 自动跑测试
├── scripts/           # smoke_stdio.py / verify_capabilities.py
├── .cursor/ .vscode/  # 客户端接入配置
└── README.md