Metadata-Version: 2.4
Name: fastmcp-glowroot-mcp
Version: 0.2.1
Summary: 基于 FastMCP 的 Glowroot Trace 分析 MCP 服务器
Author-email: "huhu.shi" <huhu.shi@hand-china.com>
License-Expression: MIT
Project-URL: Homepage, https://gitee.com/huhu234/fastmcp-glowroot-mcp
Project-URL: Repository, https://gitee.com/huhu234/fastmcp-glowroot-mcp
Project-URL: Issues, https://gitee.com/huhu234/fastmcp-glowroot-mcp/issues
Keywords: mcp,fastmcp,glowroot,traces,monitoring,java,apm,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# Glowroot MCP Server

一个基于 [FastMCP](https://gofastmcp.com/) 框架实现的 MCP（Model Context Protocol）服务器，
让 AI 助手能够分析由 [Glowroot](https://glowroot.org)（开源 APM 工具）捕获的 Java 应用程序 Trace。

## 特性

- **list_recent_errors** — 列出指定时间窗口内的最近错误
- **analyze_trace** — 深入分析指定 Trace，展示执行树和 stack trace
- **find_timeout_errors** — 查找超时类错误（SocketTimeoutException 等）
- **analyze_error_patterns** — 按事务分组分析错误模式，识别受影响最严重的事务
- **get_error_by_message** — 按错误消息内容搜索错误（例如 "NullPointerException"）
- **每个工具均支持 `glowroot_agent_id` 参数**，可在调用时动态指定 Agent ID，不再依赖环境变量


## 配置

通过环境变量或 `.env` 文件配置默认值：

```env
GLOWROOT_URL=http://localhost:4000
GLOWROOT_AGENT_ID=
```

| 变量 | 说明 | 默认值 |
|---|---|---|
| `GLOWROOT_URL` | Glowroot 实例的基础 URL | `http://localhost:4000` |
| `GLOWROOT_AGENT_ID` | 默认的 Glowroot Agent ID（多 Agent 部署时使用） | 空（单 Agent） |

> 提示：`GLOWROOT_AGENT_ID` 仅作为默认值。每个工具均支持可选的 `glowroot_agent_id` 参数，
> 调用时传入会覆盖默认值，便于在同一个 MCP 服务器中查询多个 Agent 的数据。

### Agent ID 优先级

1. 工具调用的 `glowroot_agent_id` 参数（最高）
2. 环境变量 `GLOWROOT_AGENT_ID`
3. 空字符串（单 Agent 部署）

## 传输模式

MCP 支持三种传输模式，通过环境变量 `MCP_TRANSPORT` 配置：

| 模式 | 值 | 适用场景 | 说明 |
|---|---|---|---|
| **stdio** | `stdio`（默认） | 本地部署 | 客户端启动子进程，通过 stdin/stdout 通信 |
| **Streamable HTTP** | `streamable-http` | 远程部署（推荐） | HTTP 单端点，MCP 新规范 |
| **SSE** | `sse` | 远程部署 | HTTP + Server-Sent Events，旧规范 |

远程模式相关的环境变量：

| 变量 | 说明 | 默认值 |
|---|---|---|
| `MCP_HOST` | 监听地址 | `0.0.0.0` |
| `MCP_PORT` | 监听端口 | `8000` |
| `MCP_PATH` | URL 路径 | `/mcp`（streamable-http）或 `/sse`（sse） |

## 使用

### 本地部署（stdio 模式）

stdio 是默认传输模式，**由 MCP 客户端（Claude Desktop / Kiro 等）以子进程方式拉起**，
通过 stdin/stdout 通信。**不要在终端里直接运行 `glowroot-mcp`**——它只会阻塞等待
stdin 上的 MCP 协议输入，不会交互式输出任何内容。

本地使用请直接配置客户端，见下方「MCP 配置 — 本地 stdio」。

> 若需在命令行手动验证服务器是否可启动，可加 `--help` 或指定远程传输模式（见下节），
> 例如 `MCP_TRANSPORT=streamable-http glowroot-mcp`。

### 远程部署（Streamable HTTP 模式）

在服务器上启动：

```bash
MCP_TRANSPORT=streamable-http MCP_PORT=8000 glowroot-mcp
```

服务器将在 `http://0.0.0.0:8000/mcp` 监听 MCP 请求。

### MCP 配置 — 本地 stdio（Claude Desktop / Kiro 等）

将以下配置加入 MCP 配置文件（`mcp.json`）：

```json
{
  "mcpServers": {
    "glowroot": {
      "command": "/home/YOUR_USER/.local/bin/glowroot-mcp",
      "env": {
        "GLOWROOT_URL": "http://localhost:4000",
        "GLOWROOT_AGENT_ID": ""
      }
    }
  }
}
```

> 将 `/home/YOUR_USER/.local/bin/glowroot-mcp` 替换为 `which glowroot-mcp` 的实际输出。
> 若 `glowroot-mcp` 已在 PATH 中，可直接使用 `"command": "glowroot-mcp"`。

### MCP 配置 — 远程 Streamable HTTP（Claude Desktop / Kiro 等）

```json
{
  "mcpServers": {
    "glowroot": {
      "url": "http://120.48.62.26:8000/mcp"
    }
  }
}
```

> 客户端通过网络访问远程 MCP 服务器，无需在本地安装 Python 或可执行文件。

### MCP 配置 — 远程 SSE

```json
{
  "mcpServers": {
    "glowroot": {
      "url": "http://120.48.62.26:8000/sse"
    }
  }
}
```

### 在工具调用中动态指定 Agent ID

所有工具都接受可选的 `glowroot_agent_id` 参数。例如：

```
list_recent_errors(hours_ago=1, glowroot_agent_id="agent-42")
analyze_trace(trace_id="abc-123", glowroot_agent_id="agent-42")
```

若不传入该参数，则使用环境变量 `GLOWROOT_AGENT_ID` 的值。

## 架构

本项目基于 [FastMCP](https://github.com/PrefectHQ/fastmcp) 框架开发：

- `glowroot_mcp/server.py` — 使用 `FastMCP` 声明工具，通过 `@mcp.tool` 装饰器自动生成 schema
- `glowroot_mcp/glowroot.py` — Glowroot HTTP API 客户端
- `tests/` — 单元测试（pytest + pytest-asyncio）

FastMCP 会根据函数签名和类型注解自动生成 JSON Schema，无需手写 `tools.py`。

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest
```

## 依赖

- Python 3.10+
- [FastMCP](https://gofastmcp.com/) >= 2.0.0
- [httpx](https://www.python-httpx.org/) >= 0.25.0
- [python-dotenv](https://github.com/theskumar/python-dotenv) >= 1.0.0
- 一个运行中的 [Glowroot](https://glowroot.org) 实例，用于监控 Java 应用

## License

MIT
