AI导哈

遥测工具包

MCP Toolkit是一个Python客户端工具包，用于集成Jira、GitLab和PostgreSQL等工具，并将遥测数据发送到mcp-observability-server服务器，以便在Grafana中实时监控和分析。

  • by jessebauer
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 jessebauer/mcp-obs

使用说明

MCP工具包

带有集成工具（Jira，GitLab，PostgreSQL等）的PythonMCP客户端，用于向服务器发送遥测 mcp-observability-server.

概览

  1. 开发者在 Copilot 中调用工具 → 调用通过 MCPObservabilityMiddleware.
  2. 中间件收集请求的上下文。
  3. 一个结构化的事件被发送到 POST $LOKI_SERVER_URL/loki/api/v1/push 包含标签如 gitlab_user, tool, tenant, vpn_site （用Jira用户填写）和 request_id.
  4. Loki服务器处理并保持事件；可观测性项目已经提供的 Grafana 实时显示呼叫。

没有可观察性组件在本地运行：此存储库仅拦截并发布事件。

事件合约

中间件以以下最小格式每次运行工具发送单个 JSON 有效负载：

{
  "ts": "2025-11-07T15:02:37.060Z",
  "request_id": "ana-002-150237",
  "gitlab_user": "ana.ramos",
  "client": "copilot",
  "tool": "get_gitlab_merge_request",
  "action": "invoke",
  "status": "ok",
  "latency_ms": 472,
  "vpn_site": "ana.ramos@senior.com.br",
  "host": "ana-notebook",
  "mcp_version": "1.1.0",
  "tenant": "phoenix",
  "team": "value5",
  "args_summary": "project=platform, mr=1421"
}

坎波斯临时演员（例如： tenant, team, args_summary, result_count, error_code客户必须在内部发送 telemetry 哦 mcp_log_extra在这些区块中声明的任何密钥都将作为最终事件的一部分传播，只要它不是敏感的。要在 MCP Toolkit 和可观察性服务器之间对输入进行上下文化：

  • gitlab_user, client e request_id 识别谁运行了该工具，并允许在 Grafana 中关联。
  • telemetry → { "team": "value5", "tenant": "phoenix" } 添加“按用户使用”和“按团队使用”面板中可见的标签。
  • mcp_log_extra → { "args_summary": "...", "result_count": 5 } 保存最近的日志卡 。

这种接口避免了隐含的配对：所有遥测数据都集成在一个易于理解和检查的对象中。

要求

  • Python 3.12+com pip.
  • GitHub Copilot Chat（或其他兼容的 MCP 客户端）。
  • 适用于 Jira 和 GitLab 的环境变量。
  • Loki服务器（端口3100）的HTTP访问。

快速安装

git clone <url-do-repo> ~/workspace/mcp-toolkit
cd ~/workspace/mcp-toolkit
./setup_client.sh

不使用Windows setup_client.bat两个脚本 ：

  • 创建一个虚拟环境 venv/;
  • 安装依赖关系 requirements.txt;
  • 生成（ 或更新） 文件 mcp.json 在VS代码的默认路径中；
  • 定义 LOKI_SERVER_URL 以及发送日志所需的其他变量。

手动配置（ 可选）

  1. 创建并激活虚拟环境并安装依赖关系：
    python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
  2. 在启动 IDE 之前设置环境变量 ：
    export LOKI_SERVER_URL=http://<ip-servidor>:3100
export JIRA_USERNAME=<usuario>
export JIRA_PASSWORD=<senha>
export JIRA_SERVER=https://jira.senior.com.br
export GITLAB_TOKEN=<token>
export GITLAB_URL=https://git.senior.com.br/
  3. 注册 MCP 服务器 mcp.json da IDE：
    {
  "servers": {
    "mcp-toolkit": {
      "command": "/caminho/para/venv/bin/python",
      "args": ["src/server.py"],
      "env": {
     "LOKI_SERVER_URL": "http://<ip-servidor>:3100"
      },
      "type": "stdio",
      "cwd": "/caminho/para/mcp-toolkit"
    }
  }
}

重新启动 VS Code，Copilot Chat 将识别服务器。

基本结构

mcp.json.example          # Exemplo de configuração para IDE
requirements.txt          # Dependências do servidor MCP
setup_client.sh / .bat    # Script de instalação e configuração
src/
  server.py               # Ponto de entrada MCP
  observability_middleware.py  # Envia eventos para Loki
  ...                     # Serviços e ferramentas MCP
teams.json.example        # Mapeamento opcional usuário → time

可重复使用的 Python 客户端

目录 client/ 包含包 mcp-observability-client它提供：

  • ObservabilityClient 在Loki不可用时自动备份到本地文件；
  • 遥测助手(TelemetryContext, extract_telemetry_metadata可用于任何 MCP 服务器；
  • 用于测量延迟、状态和整合工具元数据的装饰器。

安装

pip install -e ./client
# ou instale direto do Git
pip install "git+ssh://git@git.senior.com.br/one-senior/mcp-observability-server.git#subdirectory=client"

例子

from mcp_observability import init_observability
from mcp_observability.telemetry import TelemetryContext, extract_telemetry_metadata

obs = init_observability(mcp_version="2.0.0", server_name="mcp-senior-tasks")

def run_tool(args, kwargs):
    context = TelemetryContext()
    kwargs, ctx_piece = extract_telemetry_metadata(kwargs)
    context.merge(ctx_piece)
    # executar lógica...
    obs.log_event(tool="get_issue", status="ok", latency_ms=145, **context.to_payload())

咨询 client/README.md 更多细节。

如何验证遥测

  1. 确保服务器可访问：
    curl http://<ip-servidor>:3100/ready
  2. 运行任何 MCP 工具（例如列出 Jira 问题）。
  3. 打开由 Grafana 提供的 mcp-observability-server选择数据源 洛基 并围绕查询：
    {job="mcp-toolkit", gitlab_user="<seu-usuario>"}
  4. 面板将显示字段 tool, status, latency_ms, team （当设置） 和 vpn_site （使用 Jira 自动填充）。

额外调整

  • 保留Loki服务器控制；没有本地保留。
  • 匿名：默认值 MCP_ANONYMIZE_GITLAB_USER=true （或保留遗产） MCP_ANONYMIZE_GITHUB_USER=true在发送之前哈希用户。
  • 离线回退：se LOKI_SERVER_URL 未定义，事件将被记录到 logs/mcp-server.log提供此变量以确保集中发送。

这样，MCP Toolkit 就缩小到操作和向集中式图表发送可观察性事件所需的核心。只使用脚本作为快捷方式；所有相关信息都在这个README。

相关 MCP