# mcp-server

**Repository Path**: xdk_Sn0w/mcp-server

## Basic Information

- **Project Name**: mcp-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP Server

基于 MCPServer (mcp 2.0) 的工具管理服务器，支持基于角色的工具访问控制。

## 技术栈

- **Python 3.11+**
- **uv** - 极速 Python 包管理器
- **mcp (MCPServer)** - MCP 协议实现
- **FastAPI** - Web 框架
- **PostgreSQL** - 数据库
- **SQLAlchemy** - ORM

## 快速开始

### 1. 安装 uv

```bash
# macOS (Homebrew)
brew install uv

# 或使用 pip
pip install uv
```

### 2. 同步依赖（创建虚拟环境并安装依赖）

```bash
cd mcp-server
uv sync
```

### 3. 配置数据库

修改 `config/application-prod.yaml` 中的数据库配置：

```yaml
database:
  postgres:
    host: "localhost"
    port: 54320
    database: "mcp_tools"
    username: "postgres"
    password: "your_password"
```

### 4. 初始化数据

```bash
uv run python scripts/init_data.py
```

### 5. 启动服务

```bash
uv run python main.py
```

或使用 uvicorn：

```bash
uv run uvicorn main:app --host 127.0.0.1 --port 8001
```

### 6. 运行测试

```bash
uv run python tests/test_entry.py
```

## 常用 uv 命令

```bash
# 添加依赖
uv add package_name

# 添加开发依赖
uv add --dev package_name

# 移除依赖
uv remove package_name

# 运行脚本
uv run python script.py

# 锁定依赖
uv lock

# 同步依赖
uv sync
```

## 项目结构

```
mcp-server/
├── main.py                     # 主入口
├── pyproject.toml              # 项目配置（含依赖）
├── uv.lock                     # 依赖锁文件
├── config/
│   └── application-prod.yaml   # 生产配置
├── models/
│   └── database.py             # 数据库模型
├── services/
│   ├── tool_service.py         # 工具管理服务
│   ├── role_service.py         # 角色管理服务
│   ├── api_client.py           # API 调用客户端
│   └── db_query_service.py     # 数据库查询服务
├── mcp_core/
│   ├── server.py               # MCP 服务器（MCPServer 实现）
│   ├── tool_registry.py        # 动态工具注册表
│   └── auth_middleware.py      # 权限中间件
├── utils/
│   ├── config_loader.py        # 配置加载器
│   ├── db_manager.py           # 数据库管理
│   ├── response_wrapper.py     # 响应包装
│   └── exception_handler.py    # 异常处理
├── scripts/
│   └── init_data.py            # 数据初始化
└── tests/
    └── test_entry.py           # 测试入口
```

## 核心功能

### 1. 基于角色的工具访问控制

智能体访问时需携带 `X-Role-Id` 请求头，系统会根据该 ID 查询对应角色可访问的工具列表。

### 2. 两类工具支持

- **API 工具** (`tool_type: api`)：调用其他系统的 HTTP 接口，支持重试、超时、参数模板替换
- **数据库查询工具** (`tool_type: db_query`)：直接执行 SQL 查询，内置 SQL 安全校验

### 3. 统一响应格式

所有工具调用结果都包装为标准 JSON 格式：

```json
{
  "success": true,
  "data": {...},
  "error": null,
  "metadata": {...}
}
```

## API 接口

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/health` | 健康检查 |
| GET | `/api/tools` | 获取当前角色可访问的工具列表 |
| POST | `/api/tools/{tool_name}/execute` | 执行指定工具 |
| POST | `/api/tools/refresh-cache` | 刷新工具缓存 |

## MCP 端点

MCP 协议端点: `http://host:port/mcp`

## 使用示例

### 调用 API 工具

```python
import requests

# 获取工具列表
response = requests.get(
    "http://localhost:8000/api/tools",
    headers={"X-Role-Id": "role_admin"}
)

# 执行工具
response = requests.post(
    "http://localhost:8000/api/tools/get_user_info/execute",
    headers={"X-Role-Id": "role_admin"},
    json={"params": {"user_id": "123"}}
)
```

## docker 镜像构建
docker build --platform linux/amd64 -t mcp-server:v1 .


docker save -o mcp-server-v1-amd64.tar mcp-server:v1