mcpsqlpp

一种模型上下文协议（MCP）服务器，提供对 sqlpp 数据库CLI工具通过标准化的工具接口。这使得人工智能开发工具和代理能够通过安全、受控的界面与数据库进行交互。

特性

MCP协议合规性：完全支持模型上下文协议规范
双重运输支持：STDIO和HTTP+SSE传输均可实现灵活集成
数据库架构工具：访问表、视图、过程和函数模式
SQL执行：使用正确的输出格式执行SQL命令
连接管理：列出和管理数据库连接
驾驶员信息：查询可用的数据库驱动程序
综合录井：多个日志级别，可选文件日志记录和自动轮换
容器化部署：Docker支持AWS App Runner部署
生产就绪：全面的日志记录、健康检查、监控和广泛的测试覆盖

建筑

服务器充当MCP客户端和sqlpp CLI工具之间的桥梁：

MCP Client → mcp_sqlpp → sqlpp CLI (via stdin) → Database

关键组件

MCP服务器：处理协议通信和工具注册
工具处理程序：管理工具执行和参数验证
sqlpp执行器：使用具有适当错误处理的stdin接口包装sqlpp CLI执行
配置系统：通过文件、环境变量和CLI标志进行灵活配置

重要：所有SQL命令和模式查询都通过stdin使用 --stdin 旗帜。sqlpp CLI不接受SQL命令作为直接命令行参数。

有关sqlpp集成的详细信息，请参阅 SQLPP_INTEGRATION.md.

安装

先决条件

转到1.21或更高版本
sqlpp CLI工具已安装并配置

- 必需：支持的sqlpp版本 --stdin 标志和模式命令(@schema-*) - 验证：运行 sqlpp --help 确保 --stdin 标志可用 - 测试：验证架构命令是否有效： echo "@drivers" | sqlpp --stdin - 集成详细信息：参见 SQLPP_INTEGRATION.md 完成设置和配置

Docker（用于容器化部署）
AWS CLI和CDK（用于AWS部署）

地方发展

克隆存储库：

git clone https://github.com/stainedhead/gosqlpp-mcp-server.git
cd gosqlpp-mcp-server

安装依赖项：

go mod download

构建应用程序：

go build -o mcp_sqlpp ./cmd/server

使用默认配置运行：

./mcp_sqlpp

Docker部署

构建Docker镜像：

docker build -f deployment/docker/Dockerfile -t mcp_sqlpp .

运行容器：

docker run -p 8080:8080 mcp_sqlpp --transport http

配置

服务器支持多种配置方法，优先级如下：

命令行标志（最高优先级）
环境变量
配置文件
默认值（最低优先级）

配置文件

创建一个 config.yaml 文件：

server:
  transport: "stdio"  # or "http"
  host: "localhost"
  port: 8080

sqlpp:
  executable_path: ".bin"  # Directory containing sqlpp executable (default: .bin)
                                   # Relative paths are resolved relative to the MCP server binary location
  timeout: 300

log:
  level: "info"
  format: "text"  # or "json"
  file_logging: false  # Enable file logging with automatic rolling dates

aws:
  region: "us-east-1"
  environment: "development"

路径解析

两者 executable_path 日志文件使用二进制相对路径解析：

相对路径：相对于MCP服务器二进制位置解析

sqlpp:
  executable_path: ".bin"        # Resolves to: /path/to/mcp_server/.bin/sqlpp
  executable_path: "bin"         # Resolves to: /path/to/mcp_server/bin/sqlpp

log:
  file_logging: true             # Creates: /path/to/mcp_server/logs/

绝对路径：按原样使用

sqlpp:
  executable_path: "/usr/local/bin"    # Resolves to: /usr/local/bin/sqlpp

这可确保服务器找到sqlpp并在可预测的位置创建日志，而不管工作目录如何。

环境变量

所有配置选项都可以通过环境变量进行设置 GOSQLPP_MCP_ 前缀：

export GOSQLPP_MCP_SERVER_TRANSPORT=http
export GOSQLPP_MCP_SERVER_PORT=8080
export GOSQLPP_MCP_SQLPP_EXECUTABLE_PATH=/usr/local/bin
export GOSQLPP_MCP_LOG_LEVEL=debug
export GOSQLPP_MCP_LOG_FILE_LOGGING=true

命令行标志

./mcp_sqlpp --help

可用选项：

--transport, -t：传输模式（stdio、http）
--port, -p：HTTP服务器端口（用于HTTP传输）
--host：HTTP服务器主机（用于HTTP传输）
--config, -c：配置文件路径
--log-level, -l：日志级别（跟踪、调试、信息、警告、错误、致命、恐慌）
--file-logging, -f：启用具有自动滚动日期的文件日志记录

日志记录

MCP服务器提供全面的日志记录功能，具有多级和可选的文件日志记录。

日志级别

追踪：最详细，包括工具结果和sqlpp响应的截断输出预览
调试：工具执行详细信息、sqlpp命令和元数据（开发默认）
信息：一般应用程序流程和重要事件
警告/错误/致命：警告、错误和致命情况

控制台的日志

默认情况下，日志以文本格式写入控制台：

# Set log level via command line
./mcp_sqlpp --log-level debug

# Set log level via environment variable
export GOSQLPP_MCP_LOG_LEVEL=trace
./mcp_sqlpp

文件记录

启用文件日志记录以进行持久调试和监视：

# Enable via command line flag
./mcp_sqlpp --file-logging --log-level trace

# Enable via configuration file
# Set file_logging: true in config.yaml

文件日志记录功能：

自动文件命名: logs/mcp_sqlpp_YYYY-MM-DD.log
二进制相对位置：相对于MCP服务器二进制位置创建的日志
日志轮转：最大文件大小100MB，10个备份文件，30天保留期
JSON格式：结构化日志，便于更好地解析和分析
双输出：日志同时出现在控制台和文件中
压缩：旧日志文件会自动压缩

记录的内容：

MCP协议初始化和工具调用
使用参数和结果大小执行工具
sqlpp命令执行和输出（在TRACE级别截断）
错误详细信息和调试信息
绩效指标和时间安排

MCP工具

服务器提供以下MCP工具：

备注：所有工具内部都使用sqlpp --stdin 用于发送命令的接口。架构命令，如 @schema-tables SQL语句作为输入通过stdin发送到sqlpp进程。

有关MCP协议测试和工具验证的详细信息，请参阅 MCP_估计.md.

架构命令参考

支持以下架构命令（通过stdin发送到sqlpp）：

@drivers -列出所有可用的数据库驱动程序
@schema-tables [filter] -列出数据库表
@schema-views [filter] -列出数据库视图
@schema-procedures [filter] -列出存储过程
@schema-functions [filter] -列出功能
@schema-all [filter] -显示所有架构信息

架构工具

`list_schema_all`

检索所有模式信息（表、视图、过程、函数）。

参数：

connection （必填）：数据库连接名称
filter （可选）：结果过滤模式
output （可选）：输出格式（json、table、csv）

`list_schema_tables`

检索表架构信息。

参数： 同 list_schema_all

`list_schema_views`

检索视图架构信息。

参数： 同 list_schema_all

`list_schema_procedures`

检索存储过程架构信息。

参数： 同 list_schema_all

`list_schema_functions`

检索函数架构信息。

参数： 同 list_schema_all

连接管理

`list_connections`

列出所有可用的数据库连接。

参数： 无

SQL执行

`execute_sql_command`

对数据库执行SQL命令。

参数：

connection （必填）：数据库连接名称
command （必需）：要执行的SQL命令
output （可选）：输出格式

驾驶员信息

`list_drivers`

列出所有可用的数据库驱动程序。

参数： 无

使用示例

STDIO模式（适用于MCP客户端）

./mcp_sqlpp --transport stdio

HTTP模式（用于测试和web集成）

./mcp_sqlpp --transport http --port 8080

文件记录

启用具有自动滚动日期的详细文件记录：

# Enable file logging via command line
./mcp_sqlpp --file-logging --log-level trace --transport stdio

# File logging via configuration
# Set file_logging: true in config.yaml
./mcp_sqlpp --config config.yaml

启用文件日志记录时：

日志被写入 logs/mcp_sqlpp_YYYY-MM-DD.log
文件自动轮换（最大100MB，10次备份，30天保留期）
TRACE级别包括用于调试的截断输出预览
记录所有MCP调用、工具执行和sqlpp交互

测试运行状况端点：

curl http://localhost:8080/health

与MCP客户端一起使用

配置您的MCP客户端以连接到服务器：

STDIO传输：

{
  "command": "./mcp_sqlpp",
  "args": ["--transport", "stdio"]
}

HTTP传输：

{
  "url": "http://localhost:8080/mcp"
}

AWS部署

先决条件

配置具有适当权限的AWS凭据
安装AWS CDK： npm install -g aws-cdk
为GitHub操作设置OIDC（如果使用CI/CD）

手动部署

cd deployment/cdk

安装Python依赖项：

pip install -r requirements.txt

Bootstrap CDK（仅限第一次）：

cdk bootstrap

部署堆栈：

ENVIRONMENT=development cdk deploy

CI/CD部署

该项目包括用于自动部署的GitHub Actions工作流：

发展：部署到推送 develop 分支
生产：部署到推送 main 分支

所需的GitHub机密：

AWS_ROLE_ARN：OIDC身份验证的IAM角色的ARN

部署命令

从您的开发环境中：

# Deploy to development
ENVIRONMENT=development cdk deploy --profile your-aws-profile

# Deploy to production
ENVIRONMENT=production cdk deploy --profile your-aws-profile

# Destroy resources
ENVIRONMENT=development cdk destroy --profile your-aws-profile

发展

运行测试

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with detailed output
go test -v ./...

测试类别

单元测试：

配置：加载和验证配置文件和环境变量
工具执行：使用各种输入场景验证所有MCP工具
连接管理：测试连接列表和默认连接处理
日志记录功能：验证输出截断和日志记录级别

集成测试：

真正的sqlpp集成：使用实际的sqlpp可执行文件进行测试，以验证端到端功能
MCP协议合规性：验证正确的MCP握手和工具调用顺序
错误处理：测试各种故障场景和错误传播

具体测试要点：

list_connections 验证：确保正确的连接格式和默认连接检测
空结果处理：测试对空数据或缺失数据的优雅处理
输出截断：验证是否正确截断了大输出以进行日志记录
TRACE级别日志记录：验证是否正确捕获了详细的调试日志

手动测试

其他手动测试脚本可用：

# Test MCP protocol compliance
bash scripts/test-mcp-protocol.sh

# Test logging functionality  
bash scripts/test-logging.sh

# Test all tool integrations
bash scripts/test-tools.sh

有关详细的测试信息，请参阅 MCP_估计.md.

掉毛

# Install golangci-lint
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Run linter
golangci-lint run

项目结构

├── cmd/server/          # Application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── server/          # MCP server implementation
│   ├── sqlpp/           # sqlpp CLI wrapper
│   └── tools/           # MCP tool definitions
├── pkg/types/           # Shared types
├── deployment/
│   ├── cdk/             # AWS CDK infrastructure
│   └── docker/          # Docker configuration
├── .github/workflows/   # CI/CD pipelines
└── documentation/       # Additional documentation

监控和日志记录

日志记录

服务器提供具有可配置级别的结构化日志记录：

trace, debug, info, warn, error, fatal, panic

日志可以以文本或JSON格式输出，适用于不同的环境。

健康检查

HTTP传输在以下位置包含一个健康检查端点 /health 返回：

当服务正常时，HTTP 200正常
验证sqlpp可执行文件的可用性

AWS云观察

当部署到AWS App Runner时，日志会自动发送到CloudWatch，其中包含：

结构化JSON日志记录
请求/响应跟踪
误差监控
性能指标

安全考虑

输入验证：所有工具参数在执行前都经过验证
进程隔离：sqlpp作为隔离的子进程运行
非根执行：容器使用非root用户运行
网络安全：AWS部署中的可配置出口规则
秘密管理：没有硬编码的凭据或秘密

故障排除

有关全面的故障排除和MCP协议测试，请参阅 MCP_估计.md.

常见问题

“错误：未知标志：--command”

- 原因：此错误表示旧版本的MCP服务器错误地尝试使用不存在的 --command 旗帜 - 解决方案：确保您使用的是最新版本的mcp_sqlpp。服务器应使用stdin向sqlpp发送命令 - 验证：检查您的服务器版本是否包含基于stdin的实现

“无法打开文件@架构表”

- 原因：模式命令被视为文件路径，而不是特殊命令 - 解决方案：确保架构命令是通过stdin发送的，而不是作为命令行参数发送的 - 验证：架构命令在作为输入发送到时应该有效 sqlpp --stdin

未找到sqlpp

- 确保sqlpp已安装并位于PATH中 - 检查 executable_path 配置 - 验证权限

连接超时

- 增加 timeout 配置 - 检查数据库连接 - 查看sqlpp连接配置

权限不足

- 检查sqlpp可执行文件的文件权限 - 验证用户访问数据库的权限 - 查看容器用户配置

测试sqlpp集成

在使用MCP服务器之前，请验证sqlpp是否正常工作：

# Test basic connectivity
sqlpp --list-connections

# Test SQL execution
echo "SELECT 1 as test;" | sqlpp --stdin --connection main

# Test schema commands
echo "@schema-tables" | sqlpp --stdin --connection main

# Test with output formatting
echo "SELECT 'Hello World' as message;" | sqlpp --stdin --connection main --output table

有关sqlpp集成和配置的详细信息，请参阅 SQLPP_INTEGRATION.md.

调试模式

启用调试日志记录以进行详细的故障排除：

./mcp_sqlpp --log-level debug

调试文件日志记录

要进行全面调试，请启用文件日志记录以捕获所有交互：

# Enable file logging with TRACE level for maximum detail
./mcp_sqlpp --file-logging --log-level trace --transport stdio

# View recent logs
tail -f logs/mcp_sqlpp_$(date +%Y-%m-%d).log

# Search for specific tool or error logs
grep "list_connections" logs/mcp_sqlpp_*.log
grep "error" logs/mcp_sqlpp_*.log

文件日志记录捕获：

所有MCP协议消息（初始化、工具调用、响应）
带有参数和结果的工具执行详细信息
使用截断的输出预览执行sqlpp命令
错误详细信息和调试信息

贡献

分叉存储库
创建要素分支
进行更改
添加新功能的测试
运行测试和梳理
提交拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

支持

对于问题和疑问：

在GitHub上创建问题
检查文档详细指南目录：

- MCP_估计.md -MCP协议测试和故障排除 - SQLPP_INTEGRATION.md -sqlpp设置和集成详细信息

查看sqlpp文档以了解数据库特定的问题

测试

该项目包括在 test/ 目录：

test/
├── README.md                          # Detailed testing documentation
├── config/                            # Test configuration files
├── data/                              # Test data and MCP command files
├── scripts/                           # Test scripts
└── test-new-config.go                 # Configuration testing program

运行测试

# Run all unit and integration tests
make test

# Run with coverage report
make test-coverage

# Run specific test categories
go test ./internal/config/...          # Configuration tests
go test ./internal/tools/...           # Tool tests
go test ./tests/integration/...        # Integration tests

手动测试脚本

中提供了几个手动测试脚本 test/scripts/ 目录：

# Comprehensive manual testing
./test/scripts/test-manual.sh

# File logging tests
./test/scripts/test-file-logging.sh
./test/scripts/test-file-logging-tools.sh
./test/scripts/test-simple-logging.sh

所有测试脚本都应从项目根目录运行。

测试配置

针对不同场景使用特定于测试的配置：

# Test with file logging enabled
./mcp_sqlpp --config test/config/test-config-file-logging.yaml

# Test with MCP command files
cat test/data/test-mcp-commands.json | ./mcp_sqlpp --transport stdio

有关详细的测试信息，请参阅 test/README.md.

Gosqlpp MCP Server

快速接入

详细介绍

mcpsqlpp

特性

建筑

关键组件

安装

先决条件

地方发展

Docker部署

配置

配置文件

路径解析

环境变量

命令行标志

日志记录

日志级别

控制台的日志

文件记录

MCP工具

架构命令参考

架构工具

list_schema_all

list_schema_tables

list_schema_views

list_schema_procedures

list_schema_functions

连接管理

list_connections

SQL执行

execute_sql_command

驾驶员信息

list_drivers

使用示例

STDIO模式（适用于MCP客户端）

HTTP模式（用于测试和web集成）

文件记录

与MCP客户端一起使用

AWS部署

先决条件

手动部署

CI/CD部署

部署命令

发展

运行测试

测试类别

手动测试

掉毛

项目结构

监控和日志记录

日志记录

健康检查

AWS云观察

安全考虑

故障排除

常见问题

测试sqlpp集成

调试模式

调试文件日志记录

贡献

许可证

支持

测试

运行测试

手动测试脚本

测试配置

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`list_schema_all`

`list_schema_tables`

`list_schema_views`

`list_schema_procedures`

`list_schema_functions`

`list_connections`

`execute_sql_command`

`list_drivers`