Psql MCP Registry

PostgreSQL MCP 注册表

一个基于PostgreSQL的模型上下文协议（MCP）注册表，用于管理多个PostgreSQL实例。

特点/特性

• 动态实例管理在运行时添加和移除 PostgreSQL 实例
• 线程安全操作使用适当的锁定机制并发访问注册表
• “Lazy Connection”可以翻译为“懒惰连接”或“怠惰连接”，具体取决于语境和想要传达的细微差别。在技术或网络环境中，这个短语可能指的是某种低效或不活跃的网络连接状态如果某些实例不可用，注册表创建不会失败
• Docker 支持轻松创建测试用的 PostgreSQL 实例

建筑

注册表实现了一种第四种变体模式，即：

1. 即使某些实例无法连接，也会创建注册表
2. 允许通过（某种方式）对实例进行懒加载 AddInstance()
3. 为客户端提供线程安全的访问
4. 支持优雅关闭，使用 Close()

HTTP API

该服务提供了一个HTTP API，用于与MCP协议接口一起管理PostgreSQL实例。两个服务器并行运行。

环境变量

• HTTP_API_PORT - HTTP API服务器的端口（默认： 8080）
• GIN_MODE - Gin框架模式： release 或者 debug （默认： release)

API 端点

注册实例

POST /api/v1/instances
Content-Type: application/json

{
  "name": "prod_db",
  "database_name": "production",
  "description": "Production PostgreSQL instance",
  "creator_username": "admin"
}

响应（201 Created）：

{
  "id": 1,
  "name": "prod_db",
  "database_name": "production",
  "description": "Production PostgreSQL instance",
  "creator_username": "admin",
  "status": "active",
  "created_at": "2025-10-15T10:30:00Z",
  "updated_at": "2025-10-15T10:30:00Z"
}

错误响应：

• 400 Bad Request - 请求体无效或缺少必填字段
• 409 Conflict - 已经存在同名的实例
• 500 Internal Server Error - 注册失败

健康检查

GET /health

响应（200 OK）：

{
  "status": "healthy"
}

使用示例

注册一个新实例：

curl -X POST http://localhost:8080/api/v1/instances \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod_db",
    "database_name": "production",
    "description": "Production PostgreSQL instance",
    "creator_username": "admin"
  }'

检查API健康状况：

curl http://localhost:8080/health

注： 实例连接详情必须通过环境变量进行配置，遵循以下（指南/步骤/规则等，注：原文未给出具体后续内容，故“以下”后未具体翻译） PSQL_INSTANCE_{NAME}_* 模式（见下文的“环境变量格式”部分）。

快速入门

1. 启动PostgreSQL实例测试

docker-compose up -d

这将启动两个 PostgreSQL 实例：

• postgres-test（可译为“PostgreSQL测试环境”或“PostgreSQL测试实例”，具体根据上下文确定）： localhost:5432 （用户名：testuser，密码：testpass，数据库：testdb）
• postgres-test-dev 翻译成中文可以是“PostgreSQL测试开发环境”或“PostgreSQL测试-开发分支”，具体取决于上下文和用途。这里，“postgres”指的是PostgreSQL数据库，“test”表示测试，“dev”通常代表开发（development）的意思: localhost:5433 （用户名：devuser，密码：devpass，数据库：devdb）

2. 配置环境变量

复制示例环境文件：

cp .env.example .env

编辑 .env 以匹配您的实例：

# Primary instance
PSQL_INSTANCE_PROD_HOST=localhost
PSQL_INSTANCE_PROD_PORT=5432
PSQL_INSTANCE_PROD_USER=testuser
PSQL_INSTANCE_PROD_PASSWORD=testpass
PSQL_INSTANCE_PROD_DATABASE=testdb
PSQL_INSTANCE_PROD_SSLMODE=disable

# Development instance
PSQL_INSTANCE_DEV_HOST=localhost
PSQL_INSTANCE_DEV_PORT=5433
PSQL_INSTANCE_DEV_USER=devuser
PSQL_INSTANCE_DEV_PASSWORD=devpass
PSQL_INSTANCE_DEV_DATABASE=devdb
PSQL_INSTANCE_DEV_SSLMODE=disable

3. 运行测试

# Run all tests
go test ./...

# Run registry tests with verbose output
go test -v ./internal/registry/

# Check health of docker instances
docker-compose ps

使用示例

package main

import (
    "context"
    "log"
    "psql-mcp-registry/internal/registry"
    "psql-mcp-registry/internal/storage/instances"
)

func main() {
    ctx := context.Background()
    
    // Create storage backend
    storage := instances.NewPostgresStorage()
    
    // Create registry (won't fail if some instances are down)
    reg, err := registry.NewRegistry(ctx, storage)
    if err != nil {
        log.Fatal(err)
    }
    defer reg.Close()
    
    // Get a client for a specific instance
    client, ok := reg.GetClient("prod")
    if !ok {
        log.Println("prod instance not available")
        return
    }
    
    // Use the client...
    // client.Query(...)
    
    // Add a new instance dynamically
    newInstance := registry.Instance{Name: "staging"}
    if err := reg.AddInstance(ctx, newInstance); err != nil {
        log.Printf("Failed to add staging: %v", err)
    }
    
    // List all available instances
    instances := reg.ListInstances()
    log.Printf("Available instances: %v", instances)
}

注册表API

NewRegistry(ctx, storage) (*Registry, error)

创建一个新的注册表。即使某些实例无法连接，操作也会成功。

AddInstance(ctx, instance) error

向注册表中添加一个新实例（懒加载）。

GetClient(name) (*pg.Client, bool)

返回给定实例名称的客户端。

RemoveInstance(name) error

移除一个实例并关闭其连接。

ListInstances() []string

返回所有已注册的实例名称。

Close() error

关闭所有客户端连接。

测试

测试套件使用模拟对象来避免需要实际的数据库连接：

• 测试新注册表成功验证在失败实例情况下注册表的创建情况
• 测试新注册表_列出实例错误测试存储错误处理
• 测试注册表获取客户端客户端检索测试
• TestRegistry_ListInstances 翻译为中文是：“测试注册表_列出实例”实例测试列表
• 测试注册表_添加实例_无配置测试：添加无配置的实例
• 通过实例名加载配置的测试实例成功测试配置加载
• 测试实例_按实例名称加载配置_缺失主机缺少配置的测试

Docker 命令

# Start instances
docker-compose up -d

# View logs
docker-compose logs -f

# Stop instances
docker-compose down

# Stop and remove volumes (clean slate)
docker-compose down -v

# Check instance health
docker-compose ps

环境变量格式

实例配置遵循以下模式：

PSQL_INSTANCE__HOST=hostname
PSQL_INSTANCE__PORT=5432
PSQL_INSTANCE__USER=username
PSQL_INSTANCE__PASSWORD=password
PSQL_INSTANCE__DATABASE=dbname
PSQL_INSTANCE__SSLMODE=disable
PSQL_INSTANCE__MAX_OPEN_CONNS=25
PSQL_INSTANCE__MAX_IDLE_CONNS=10

哪里 ` 是大写实例名称（例如。， PROD， DEV， STAGING`）。

许可证

麻省理工学院（MIT）