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  ~/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

1. 在启动 IDE 之前设置环境变量 ：

   export LOKI_SERVER_URL=http://:3100
   export JIRA_USERNAME=
   export JIRA_PASSWORD=
   export JIRA_SERVER=https://jira.senior.com.br
   export GITLAB_TOKEN=
   export GITLAB_URL=https://git.senior.com.br/

1. 注册 MCP 服务器 mcp.json da IDE：

   {
     "servers": {
       "mcp-toolkit": {
         "command": "/caminho/para/venv/bin/python",
         "args": ["src/server.py"],
         "env": {
        "LOKI_SERVER_URL": "http://: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://:3100/ready

1. 运行任何 MCP 工具（例如列出 Jira 问题）。
2. 打开由 Grafana 提供的 mcp-observability-server选择数据源 洛基 并围绕查询：

   {job="mcp-toolkit", gitlab_user=""}

1. 面板将显示字段 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。