Tj Db MCP

TJ_DB MCP服务器

一种模型上下文协议（MCP）服务器，提供对TJ_DB报告表的只读访问。该服务器使人工智能助手（如克劳德）能够通过安全、经过验证的界面查询销售和库存数据。

概述

TJ_DB MCP服务器公开了六个预构建的报告表，其中包含销售和现存量（QOH）库存数据：

• dbo.TJ_60DaySales -60天的销售数据
• dbo.TJ_90DaySales -90天的销售数据
• dbo.TJ_90DayQOHCompany -90天公司级库存数据
• dbo.TJ_90DaySales_QOH_w_Pricepoint -销售/库存与定价相结合
• dbo.TJ_120DaySales -120天的销售数据
• dbo.TJ_120DayQOHCompany -120天公司级库存数据

特性

• 只读访问：只允许SELECT查询
• 查询验证：自动验证以防止破坏性操作
• 苏格兰和南方能源公司运输：服务器发送事件以实现高效的实时通信
• 基于Docker：在安全、隔离的容器中运行
• 健康监测：容器编排的内置健康检查
• 综合录井：调试和监控的详细日志

快速开始

先决条件

• 已安装Docker和Docker Compose
• 访问192.168.1.3上的SQL Server
• 的数据库凭据 tjtools 用户

安装

1. 克隆或导航到项目目录：

   cd /home/administrator/tj-db-mcp

1. 构建并启动容器：

   docker-compose up -d --build

1. 检查日志：

   docker-compose logs -f

1. 验证服务器是否正在运行：

   curl http://localhost:5002/health

配置

环境变量

配置是通过环境变量进行管理的 docker-compose.yml:

DB_SERVER=192.168.1.3          # SQL Server hostname/IP
DB_DATABASE=TJ_DB              # Database name
DB_USERNAME=tjtools            # Database username
DB_PASSWORD=Gr33n21!           # Database password
DB_DRIVER=ODBC Driver 18 for SQL Server
PORT=5002                      # Server port
HOST=0.0.0.0                   # Bind address
LOG_DIR=/app/logs              # Log directory

端口配置

服务器在端口上运行 5002 默认情况下。要更改：

1. 更新 PORT 在 docker-compose.yml
2. 更新端口映射： ":5002"
3. 重建： docker-compose up -d --build

MCP工具

1.query_tj_db

对TJ_DB报告表执行只读SELECT查询。

输入:

{
  "sql": "SELECT TOP 100 * FROM dbo.TJ_90DaySales ORDER BY SaleDate DESC"
}

输出:

Query returned 100 rows:

[
  {"SaleDate": "2026-02-01", "ProductID": "12345", ...},
  ...
]

安全：只允许使用SELECT语句。插入/更新/删除等操作被拒绝。

2.get_tj_schema

检索所有可用表的架构文档。

输入:

{}

输出：带有表描述、常见用例和示例查询的Markdown文档。

建筑

组件

1. 服务器.py：主MCP服务器实现

- 数据库连接管理 - 查询验证和执行 - 工具操作员 - SSE运输

1. Docker容器:

- Python 3.12精简基础镜像 - SQL Server的ODBC驱动程序18 - 非root用户（UID 1000） - 具有tmpfs卷的只读文件系统 - 资源限制（1个CPU，512MB RAM）

1. 端点:

- /sse -SSE连接端点 - /messages -MCP消息的POST端点 - /health -健康检查端点

安全特性

• 只读数据库访问: ApplicationIntent=ReadOnly
• 查询验证：阻止危险的SQL关键字
• 非根容器：以用户身份运行 mcp （UID 1000）
• 只读文件系统：防止容器修改
• 没有新特权：安全强化
• 资源限制：防止资源耗尽

与Claude一起使用

桌面应用

1. 在Claude Desktop设置中配置MCP服务器
2. 添加SSE端点： http://localhost:5002/sse
3. Claude现在可以使用自然语言查询TJ_DB数据

API集成

使用MCP SDK连接到MCP服务器：

from mcp import ClientSession
from mcp.client.sse import sse_client

async with sse_client("http://localhost:5002/sse") as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize the connection
        await session.initialize()

        # Call a tool
        result = await session.call_tool("query_tj_db", {
            "sql": "SELECT TOP 10 * FROM dbo.TJ_90DaySales"
        })

监控

检查服务器状态

# Check if container is running
docker ps | grep tj-db-mcp

# View real-time logs
docker-compose logs -f

# Check health status
curl http://localhost:5002/health

日志文件

日志存储在 /home/administrator/tj-db-mcp/logs/:

# View recent logs
tail -f logs/tj-db-mcp.log

# Search for errors
grep ERROR logs/tj-db-mcp.log

资源监控

# Check container resource usage
docker stats tj-db-mcp

维护

更新容器

# Stop container
docker-compose down

# Rebuild with latest changes
docker-compose up -d --build

# Verify
docker-compose logs -f

重新启动容器

docker-compose restart

查看数据库连接信息

docker-compose exec tj-db-mcp env | grep DB_

故障排除

容器无法启动

1. 检查日志： docker-compose logs
2. 验证数据库连接：

   docker-compose run --rm tj-db-mcp python -c "import pyodbc; print('Success')"

1. 检查端口冲突： netstat -tulpn | grep 5002

数据库连接失败

1. 验证SQL Server是否可访问：

   telnet 192.168.1.3 1433

1. 检查凭据 docker-compose.yml
2. 验证防火墙规则
3. 检查SQL Server身份验证模式

查询错误

1. 直接在SQL Server上测试查询
2. 检查查询验证（仅限SELECT）
3. 验证表名和权限
4. 检查日志以获取详细的错误消息

健康检查失败

# Manual health check
curl -v http://localhost:5002/health

# Check inside container
docker-compose exec tj-db-mcp curl http://localhost:5002/health

与nginx集成

Cooper将配置nginx将请求路由到此MCP服务器。典型配置：

location /tj-db-mcp/ {
    proxy_pass http://localhost:5002/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}

发展

本地开发

1. 安装依赖项：

   pip install -r requirements.txt

1. 设置环境变量：

   export DB_SERVER=192.168.1.3
   export DB_DATABASE=TJ_DB
   export DB_USERNAME=tjtools
   export DB_PASSWORD=Gr33n21!
   export PORT=5002

1. 在本地运行：

   python server.py

测试

# Test schema tool
curl -X POST http://localhost:5002/messages \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_tj_schema", "arguments": {}}'

# Test query tool
curl -X POST http://localhost:5002/messages \
  -H "Content-Type: application/json" \
  -d '{"tool": "query_tj_db", "arguments": {"sql": "SELECT TOP 5 * FROM dbo.TJ_90DaySales"}}'

架构文档

看 schema_rules.md 所有可用表格的详细文档，包括：

• 表说明和目的
• 常见用例
• 查询示例
• 性能优化提示
• 数据新鲜度信息

相关项目

• 库珀时间表MCP：WhenWork调度分析MCP服务器
• 地点： /home/administrator/wiw-mcp

许可证

仅供内部使用。不用于公开发行。

支持

对于问题或疑问：

• 检查日志： docker-compose logs -f
• 审查文件： schema_rules.md
• 联系人：数据库管理员

版本

• 版本: 1.0.0
• 最后更新: 2026-02-02
• python: 3.12
• MCP-SDK: 0.9.0+