使用说明

MCP PostgreSQL服务器

一个干净、模块化的Flask应用程序，与PostgreSQL集成，使用MCP（模型上下文协议）进行数据库操作，并与LangChain/Ollama集成。

先决条件

Docker&Docker编写 -用于PostgreSQL数据库
Python 3.11+ -对于Flask应用程序
没有 -LLM功能(点击此处下载)

项目结构

├── src/
│   ├── config/
│   │   └── database.py          # Database connection configuration
│   ├── database/
│   │   ├── user_operations.py   # User CRUD operations
│   │   └── init.sql             # Database initialization
│   ├── middleware/
│   │   ├── auth.py              # JWT authentication
│   │   ├── rate_limiter.py      # Rate limiting middleware
│   │   └── security.py          # Security middleware
│   ├── services/
│   │   └── llm_service.py       # LangChain LLM service
│   └── routes/
│       ├── auth_routes.py       # Authentication endpoints
│       └── mcp_routes.py        # MCP tool definitions and routing
├── tests/                       # Comprehensive test suite (72 tests)
├── app.py                       # Main Flask application
├── pytest.ini                  # Test configuration
├── requirements.txt             # Python dependencies
├── docker-compose.yml           # Docker configuration
└── Dockerfile                   # Container build instructions

快速入门（Docker-推荐）

1.配置环境

cp .env.example .env
# Edit .env file with your settings if needed

2.启动整个堆栈

docker-compose up -d

3.测试服务

curl http://localhost:8000/health

手动设置

1.创建虚拟环境

python -m venv venv
.\venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

2.安装依赖项

pip install -r requirements.txt

3.配置环境

cp .env.example .env
# Edit .env file with your settings

4.启动PostgreSQL容器

docker-compose up postgres -d

5.运行MCP服务器

python app.py

配置

环境变量

所有配置都是通过环境变量处理的。看 .env.example 对于所有可用选项：

数据库：PostgreSQL连接设置
没有：LLM模型和端点配置
烧瓶：服务器主机、端口和调试设置
码头工人：容器特定的覆盖

应用程序使用 LangChain独家 LLM互动。

MCP工具

统一服务器提供以下MCP工具：

insert_user -创建新用户
get_users -检索所有用户
get_user_by_id -获取特定用户
update_user -更新现有用户
delete_user -删除用户
query_with_llm -自然语言数据库查询

API终点

GET /health -健康检查（显示模式和连接）
GET /mcp/tools -列出可用的MCP工具（需要身份验证）
POST /mcp/call_tool -执行MCP工具（需要身份验证）
POST /auth/login -生成身份验证令牌
GET /auth/verify -验证令牌有效性

认证

所有MCP端点都需要JWT身份验证。使用以下步骤：

1.生成令牌

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

答复：

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": 1, "username": "admin" }
}

2.在请求中使用令牌

将令牌添加到 Authorization 头球

curl -X POST http://localhost:8000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{"name": "get_users", "arguments": {}}'

测试

使用cURL：

# Health check
curl http://localhost:8000/health

# Get authentication token first
TOKEN=$(curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}' \
  | jq -r .token)

# List available tools
curl http://localhost:8000/mcp/tools \
  -H "Authorization: Bearer $TOKEN"

# Get all users
curl http://localhost:8000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "get_users", "arguments": {}}'

# Insert user
curl http://localhost:8000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "insert_user", "arguments": {"username": "test_user", "email": "test@example.com", "first_name": "Test", "last_name": "User"}}'

# Natural language query (requires Ollama)
curl http://localhost:8000/mcp/call_tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "query_with_llm", "arguments": {"query": "Show me all users"}}'

与邮递员：

获取令牌：POST http://localhost:8000/auth/login
- 主体： {"username": "admin", "password": "password"}
- 复制 token 从响应
健康检查：获取 http://localhost:8000/health （无需身份验证）
列出工具：获取 http://localhost:8000/mcp/tools
- 标题： Authorization: Bearer YOUR_TOKEN
呼叫工具：POST http://localhost:8000/mcp/call_tool
- 标题： Authorization: Bearer YOUR_TOKEN
- 正文：JSON工具调用

工具调用体示例：

{
  "name": "query_with_llm",
  "arguments": {
    "query": "Show me all users in a clean format"
  }
}

Ollama设置

安装Ollama 从https://ollama.ai/
启动Ollama服务:
```
ollama serve
```
拉取所需模型:
```
ollama pull llama3.2
```
确认Ollama正在运行:
```
curl http://localhost:11434/api/tags
```

运行测试

本地测试

# Run all tests
python -m pytest tests/

# Run with verbose output
python -m pytest tests/ -v

# Run specific test categories
python -m pytest -m sanity     # Quick health checks
python -m pytest -m unit       # Unit tests
python -m pytest -m integration # Integration tests
python -m pytest -m e2e        # End-to-end tests

Docker测试

# Run tests in Docker container
docker run --rm mcp-postgresql-server python -m pytest tests/

# Run with verbose output
docker run --rm mcp-postgresql-server python -m pytest tests/ -v