# mteam-mcp-server
`mteam-mcp-server` 是一个基于 `FastMCP` 框架开发的 MCP（Model Context Protocol）服务器，让 AI 助手（如 Claude、Cursor 等）能够直接调用 M-Team（馒头）私有种子站的 API，实现资源搜索、种子详情获取和种子文件下载等功能。

## 技术栈
- `Python 3.x` - 主要编程语言，用于实现 MCP 服务器的核心逻辑。
- `FastMCP` -  一个轻量级的 Python 框架，用于构建 MCP 服务器，提供了简洁的接口定义和请求处理机制。
- `mteam 0.1.5` - M-Team Site API Client, 用于与 M-Team 站点进行交互, 包括登录、搜索、获取种子详情和下载种子文件等功能。使用说明参考文件 `mteam-0.1.5.md`.

## 功能
- **资源搜索**：AI 助手可以通过 MCP 协议发送搜索请求，服务器会调用 M-Team API 进行搜索，并将结果返回给 AI 助手。
- **种子详情获取**：AI 助手可以请求特定种子的详细信息，服务器会调用 M-Team API 获取并返回相关数据。
- **种子文件下载**：AI 助手可以请求下载特定种子的文件，服务器会调用 M-Team API 获取下载链接，并将链接返回给 AI 助手。

## 工程初始化

由于 `FastMCP`（依赖 `pydantic v2`）与 `mteam 0.1.5`（依赖 `pydantic v1`）存在依赖冲突，项目采用“双虚拟环境”模式：

- 主环境 `.venv`：运行 MCP 服务（`Python + FastMCP`）
- Worker 环境 `.venv-mteam`：运行 `mteam 0.1.5` 客户端逻辑

### 1) 配置环境变量

复制并编辑 `.env`：

- `MTEAM_API_KEY`：你的 M-Team API Key
- `MTEAM_BASE_URL`：API 地址
- `MTEAM_WORKER_PYTHON`：可选，默认是 `.venv-mteam/bin/python`

### 2) 初始化主环境

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
```

### 3) 初始化 Worker 环境

```bash
python3 -m venv .venv-mteam
source .venv-mteam/bin/activate
pip install --upgrade pip
pip install -r worker/requirements.txt
```

### 4) 启动 MCP 服务

```bash
source .venv/bin/activate
mteam-mcp-server
```

如果你希望指定 Worker Python 路径：

```bash
export MTEAM_WORKER_PYTHON=/absolute/path/to/.venv-mteam/bin/python
```

## MCP Server 配置示例

以下示例默认项目路径为：`/Users/penglinwei/Codes/mteam-mcp-server`。

### 1) OpenClaw（兼容 `mcpServers` 格式）

可放入 OpenClaw 的 MCP 配置文件（若你的 OpenClaw 使用 `mcpServers` 字段）：

```json
{
	"mcpServers": {
		"mteam": {
			"command": "/Users/penglinwei/Codes/mteam-mcp-server/.venv/bin/python",
			"args": [
				"-m",
				"mteam_mcp_server.server"
			],
			"env": {
				"MTEAM_API_KEY": "your_api_key_here",
				"MTEAM_BASE_URL": "https://api.m-team.io/api",
				"MTEAM_WORKER_PYTHON": "/Users/penglinwei/Codes/mteam-mcp-server/.venv-mteam/bin/python"
			}
		}
	}
}
```

### 2) Claude Code

可放入 Claude Code 使用的 MCP 配置（同样是 `mcpServers` 结构）：

```json
{
	"mcpServers": {
		"mteam": {
			"command": "/Users/penglinwei/Codes/mteam-mcp-server/.venv/bin/python",
			"args": [
				"-m",
				"mteam_mcp_server.server"
			],
			"env": {
				"MTEAM_API_KEY": "your_api_key_here",
				"MTEAM_BASE_URL": "https://api.m-team.io/api",
				"MTEAM_WORKER_PYTHON": "/Users/penglinwei/Codes/mteam-mcp-server/.venv-mteam/bin/python"
			}
		}
	}
}
```

### 3) GitHub Copilot（VS Code）

推荐在工作区创建 `.vscode/mcp.json`：

```json
{
	"servers": {
		"mteam": {
			"type": "stdio",
			"command": "/Users/penglinwei/Codes/mteam-mcp-server/.venv/bin/python",
			"args": [
				"-m",
				"mteam_mcp_server.server"
			],
			"env": {
				"MTEAM_API_KEY": "your_api_key_here",
				"MTEAM_BASE_URL": "https://api.m-team.io/api",
				"MTEAM_WORKER_PYTHON": "/Users/penglinwei/Codes/mteam-mcp-server/.venv-mteam/bin/python"
			}
		}
	}
}
```

> 提示：如果你已经在项目根目录维护了 `.env`，也可以只保留 `MTEAM_WORKER_PYTHON`，其余变量通过 `.env` 加载。