Teradata Gcfr MCP Server

teradata gcfr mcp服务器

公开Teradata GCFR（全局控制框架）的MCP（模型上下文协议）服务器 存储库）操作报告作为自然语言工具可供Claude Desktop使用 代码、VS代码复制聊天和任何其他MCP兼容客户端。将Claude连接到您的Teradata 环境，并提出诸如“向我展示自昨天以来失败的流程”或“是什么 本周流速度最慢”——无需编写SQL。

______________________________________________________________________

先决条件

______________________________________________________________________

运作原理

服务器架构：

1. 入口点 (server.py)--初始化连接池，注册所有工具，应用配置文件筛选，并启动MCP服务器。
2. 连接池 (db.py)--Teradata连接的线程安全池，具有可配置的大小、溢出和超时。查询在短暂故障时会自动重新连接一次。
3. 工具模块 (tools/*.py)——7类MCP工具：

- 流 （3个工具）：直播状态和业务日期跟踪 - 过程 （3个工具）：流程执行历史和当前状态 - 负载 （3个工具）：数据摄取统计和注册审计 - 变换 （5个工具）：转换统计数据、性能排名和趋势分析 - 错误 （3个工具）：错误日志、执行跟踪和失败的进程诊断 - 服务级别协议 （2个工具）：服务级别协议合规性报告 - 世系 （2个工具）：数据沿袭跟踪和健康检查

1. 定制工具 (tool_loader.py)--从加载的YAML定义的SQL工具 CONFIG_DIR 在启动时，允许在没有Python代码的情况下进行特定于站点的报告。

查询执行：

• 所有SQL都使用参数化查询(? 占位符）以防止注射。
• 架构/表名称来自 settings.py 常量，从不接受用户输入。
• 通过强制执行每次查询超时 GCFR_QUERY_TIMEOUT （默认120秒）。
• 查询上限为 GCFR_MAX_ROWS （默认500行）。
• 结果在失败时作为结构化错误字典返回，没有异常。

运输方式：

______________________________________________________________________

最近的改进

查询超时强制 (2025-04-02)

• GCFR_QUERY_TIMEOUT 现在已连接到 teradatasql.connect() 在连接初始化时
• 超过超时的查询将在数据库级别中断（不再有失控的查询）
• 超时统一适用于所有工具查询

HTTP挂载路径支持 (2025-04-02)

• MCP_PATH 设置现在已正确传递给FastMCP mcp.run() 呼叫
• HTTP传输现在挂载在配置的路径上（例如。， /mcp/ → http://127.0.0.1:8001/mcp/)
• 实现更好的URL层次结构和多服务器配置

连接池稳健性

• 在瞬态故障（过时连接、临时网络问题）时自动重新连接一次
• 为Teradata工作负载管理归因在所有连接上设置QueryBand
• 通过超时感知阻塞优雅地处理连接耗尽

______________________________________________________________________

快速启动

地方发展（推荐）

git clone 
cd teradata-gcfr-mcp-server
uv sync
cp .env.example .env          # Edit with your Teradata credentials
MCP_TRANSPORT=sse uv run teradata-gcfr-mcp-server  # Or use stdio for Claude Desktop

这 MCP_TRANSPORT 默认为 stdio （适用于Claude Desktop），但是 sse 对调试很有用 stderr上有可见的日志输出。

______________________________________________________________________

开发安装

git clone 
cd teradata-gcfr-mcp-server

# Install all dependencies including dev extras
uv sync

# Run linting and type checks before making changes
uv run ruff check src/
uv run mypy src/

# Run unit tests (no Teradata connection required)
uv run pytest tests/unit/ -v

# Run the server locally in development mode
MCP_TRANSPORT=sse uv run teradata-gcfr-mcp-server

复制 .env.example 到 .env 并使用您的Teradata凭据进行更新。服务器将使用 环境变量自动。

验证门（提交前运行）：

所有三项检查必须零错误通过：

uv run ruff check src/        # Linting
uv run mypy src/              # Type checking (strict)
uv run pytest tests/unit/ -v  # Unit tests (76 tests)

______________________________________________________________________

配置参考

所有设置都是从环境变量或 .env 工作目录中的文件。

运输配置注意事项：

• MCP_HOST 和 MCP_PORT 是FastMCP内部设置，在运行时无法更改。服务器绑定到这些值，但MCP框架控制实际的绑定。只有当你理解其中的含义时，才能修改它们。
• MCP_PATH 正确布线并控制HTTP安装点（例如。， /mcp/ → http://host:port/mcp/).
• GCFR_QUERY_TIMEOUT 现在已连接到 teradatasql.connect()，确保所有查询都遵守配置的超时。

______________________________________________________________________

档案

配置文件限制了哪些工具暴露给MCP客户端。通过设置 PROFILE env变量或 --profile CLI标志。

all （默认）

所有工具都可用。

ops

专注于实时操作监控：

gcfr_stream_status, gcfr_current_stream_status, gcfr_stream_business_date, gcfr_current_process_status, gcfr_process_history, gcfr_process_status_summary, gcfr_failed_processes, gcfr_error_log, gcfr_execution_log, gcfr_load_status, gcfr_health_check

performance

专注于SLA和吞吐量分析：

gcfr_sla_process_report, gcfr_sla_stream_report, gcfr_top_slowest_processes, gcfr_top_slowest_streams, gcfr_data_trend_loads, gcfr_data_trend_transforms, gcfr_stream_status, gcfr_health_check

lineage

专注于数据沿袭和注册审计：

gcfr_data_lineage, gcfr_dataset_registered, gcfr_load_stats, gcfr_transform_stats, gcfr_health_check

______________________________________________________________________

可用MCP工具（共22个）

所有工具都是针对GCFR操作视图的只读查询。无修改数据。

流（3个工具）

• gcfr_stream_status --日期范围的历史记录和完成状态
• gcfr_current_stream_status --实时流状态（正在运行）
• gcfr_stream_business_date --流的当前、上一个、下一个业务日期

流程（3个工具）

• gcfr_process_status_summary --业务日期的所有流程（已完成与未完成）
• gcfr_current_process_status --实时进程状态
• gcfr_process_history --执行历史，包括时间和结果

负载（3个工具）

• gcfr_load_status --哪些暂存表已成功加载以及行数
• gcfr_load_stats --详细的负载统计数据（拒绝、ET/UV违规、错误）
• gcfr_dataset_registered --已注册用于处理的源数据集

转换（5个工具）

• gcfr_transform_stats --每个进程插入/更新/删除的行
• gcfr_top_slowest_processes --按运行时间排列的前N个最慢进程
• gcfr_top_slowest_streams --按经过时间排名的前N个最慢流
• gcfr_data_trend_loads --日负荷量趋势
• gcfr_data_trend_transforms --每日转换量趋势

错误（3个工具）

• gcfr_failed_processes --带有错误详细信息的失败流程实例
• gcfr_error_log --用于根本原因调查的原始错误日志条目
• gcfr_execution_log --步骤级执行跟踪（仅调试级）

SLA（2个工具）

• gcfr_sla_process_report --预期与实际流程时间安排和SLA合规性
• gcfr_sla_stream_report --预期流持续时间与实际流持续时间和SLA合规性

谱系（2个工具）

• gcfr_data_lineage --将目标表追溯到源对象
• gcfr_health_check --验证GCFR数据库是否可访问

______________________________________________________________________

数据库命名

GCFR使用两层不同的数据库：

从不 参考 GDEV1_GCFR （无T或V后缀）--该数据库不存在。所有工具 查询的目标是 GDEV1V_* 视图层。仅 gcfr_health_check 触碰 GDEV1T_GCFR 到 验证物理表是否可访问。

______________________________________________________________________

所需Teradata权限

服务器帐户需要 SELECT 三个视图层数据库的特权：

GRANT SELECT ON GDEV1V_GCFR  TO ;
GRANT SELECT ON GDEV1V_OPR   TO ;
GRANT SELECT ON GDEV1V_UTLFW TO ;
-- For health-check (optional):
GRANT SELECT ON GDEV1T_GCFR  TO ;

不 INSERT, UPDATE, DELETE，或者需要DDL权限——服务器是只读的。

______________________________________________________________________

Claude桌面配置

将以下内容添加到您的 claude_desktop_config.json （替换凭证值）：

{
  "mcpServers": {
    "teradata-gcfr": {
      "command": "uvx",
      "args": ["teradata-gcfr-mcp-server"],
      "env": {
        "DATABASE_URI": "teradata://myuser:mypass@gdev1-host:1025/GDEV1V_GCFR",
        "LOGMECH": "TD2",
        "GCFR_VIEW_DB": "GDEV1V_GCFR",
        "GCFR_OPR_DB": "GDEV1V_OPR",
        "GCFR_UTLFW_DB": "GDEV1V_UTLFW",
        "GCFR_TABLE_DB": "GDEV1T_GCFR",
        "MCP_TRANSPORT": "stdio",
        "PROFILE": "all"
      }
    }
  }
}

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

______________________________________________________________________

VS代码/副驾驶聊天配置

添加到您的VS代码 settings.json 或工作空间 .vscode/mcp.json.SSE运输是 建议使用VS代码：

{
  "mcp": {
    "servers": {
      "teradata-gcfr": {
        "type": "sse",
        "url": "http://127.0.0.1:8001/sse",
        "env": {}
      }
    }
  }
}

然后使用以下命令运行服务器：

MCP_TRANSPORT=sse uv run teradata-gcfr-mcp-server

______________________________________________________________________

Docker快速入门

# Build image
docker build -t gcfr-mcp .

# Run with an .env file
docker run --rm --env-file .env -p 8001:8001 gcfr-mcp

# Or use docker-compose (starts with streamable-http transport)
docker compose up

这 docker-compose.yml 山丘 ./gcfr_custom_tools.yml 放入集装箱 /app/gcfr_custom_tools.yml （只读）。创建此文件以添加特定于站点的工具；如果它 不存在，容器启动时没有自定义工具。

______________________________________________________________________

自定义工具（YAML）

通过放置一个 *_tools.yml 归档 CONFIG_DIR （默认为 .，当前工作目录）。

示例-- gcfr_custom_tools.yml:

tools:
  - name: gcfr_my_site_report
    description: "Latest 20 stream records for this site"
    sql: >
      SELECT TOP 20
        Stream_Key, Stream_Name, Business_Date, Stream_Status
      FROM {gcfr_opr_db}.GCFR_RV_Stream
      ORDER BY Business_Date DESC

支持的SQL占位符：

自定义工具是零参数的——它们直接使用 GCFR_MAX_ROWS 行限制自动应用。工具名称必须跟在后面 gcfr_ 前缀约定，使配置文件过滤和命名约定保持一致。

______________________________________________________________________

例题

服务器连接后，以下问题对Claude来说是开箱即用的：

1. “显示自昨天以来所有失败的进程。”
2. “流42的当前状态是什么？”
3. “哪些流尚未完成今天的业务日期？”
4. “给我本周最慢的10个流程。”
5. “显示2024年1月1日至2024年01月31日期间LOAD_CUSTOMER_DAILY进程的SLA报告。”
6. “哪些数据集在GCFR中注册？”
7. “列出目标表CUSTOMER_DIM的沿袭。”
8. “显示过去7天的转换统计数据。”
9. “GCFR数据库是否可访问？运行健康检查。”
10. “今天执行日志中出现了哪些错误？”

______________________________________________________________________

过梁和类型检查

# Lint
uv run ruff check src/

# Auto-fix lint issues
uv run ruff check --fix src/

# Type checking (strict)
uv run mypy src/

______________________________________________________________________

运行测试

单元测试（无需Teradata连接）

uv run pytest tests/unit/ -v

所有数据库调用都被模拟——单元测试离线运行。

集成测试（需要GDEV1网络接入）

uv run pytest tests/integration/ -v

集成测试尚未实施。欢迎捐款--见 CLAUDE.md 为了 待处理工作列表。

跳过慢速测试

uv run pytest tests/unit/ -v -m "not slow"

______________________________________________________________________

架构和设计模式

看 CLAUDE.md 在全面开发人员文档的存储库中，包括：

• 异步/同步拆分 --为什么MCP工具包装器是异步的，但DB逻辑是同步的
• 动态日期默认值 --如何避免函数签名中的日期冻结
• 仅参数化SQL --用户输入与模式名称的安全模型
• 重新连接一次模式 --连接池中的瞬态故障处理
• TOP条款注入 --为什么以及如何透明地应用行限制
• 测试模式 --如何在不影响Teradata的情况下模拟数据库调用
• 自定义工具加载 --YAML驱动的工具注册和占位符替换
• 配置文件过滤 --基于角色的访问控制在启动时是如何工作的

______________________________________________________________________

设计验证

此服务器已针对上游进行了验证 Teradata/teradata-mcp-server 获取架构最佳实践和经验教训。主要区别：

这两种实现都是生产就绪的，主要在范围上有所不同（GCFR特定与通用Teradata） 以及部署策略（轻量级与功能丰富）。

______________________________________________________________________

故障排除