Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,28 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| `pt-snap focus` | Set and manage analysis focus (database + device) |
| `pt-snap query` | Run memory analysis queries |
| `pt-snap config` | Manage global configuration |
| `pt-snap-mcp` | Start the MCP server for agent integration |

## MCP Server

`pt-snap-cli` provides an MCP (Model Context Protocol) server so AI agents can interact with PyTorch memory snapshots programmatically.

```bash
# Start the MCP server
pt-snap-mcp
```

The server exposes the following tools:

| Tool | Description |
|------|-------------|
| `get_focus` | Get the current analysis focus |
| `set_focus` | Set focus to a database and optional device |
| `list_templates` | List available query templates |
| `get_template_info` | Get template details and parameters |
| `execute_query` | Run a query template against the focused database |

See the [MCP guide](docs/en/mcp.md) for setup and usage details.

## Documentation

Expand All @@ -43,6 +65,7 @@ See the [full quick start guide](docs/en/quickstart.md) for a walkthrough.
| Getting started | [Quick Start](docs/en/quickstart.md) |
| Managing focus | [Focus Management](docs/en/focus-management.md) |
| Running queries | [Querying](docs/en/querying.md) |
| MCP server | [MCP Guide](docs/en/mcp.md) |
| Database format | [SnapshotDB Schema](docs/en/database.md) |
| Python API | [ResultMapper API](docs/en/result-mapper-api.md) |

Expand All @@ -65,6 +88,7 @@ pt-snap-cli/
│ ├── cli.py # CLI entry point
│ ├── context.py # Database context manager
│ ├── config.py # Focus management
│ ├── api.py # Python API layer
│ ├── query/
│ │ ├── builder.py # Query builder
│ │ ├── executor.py # Query executor
Expand All @@ -73,7 +97,8 @@ pt-snap-cli/
│ │ ├── condition.py # Query conditions
│ │ ├── config.py # Query configuration
│ │ └── templates/ # Query templates
│ └── models/ # Data models
│ ├── models/ # Data models
│ └── mcp/ # MCP server for agent integration
├── tests/ # Test files
├── examples/ # Example data
└── docs/ # Documentation
Expand Down
27 changes: 26 additions & 1 deletion README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,28 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
| `pt-snap focus` | 设置和管理分析焦点(数据库 + 设备) |
| `pt-snap query` | 运行内存分析查询 |
| `pt-snap config` | 管理全局配置 |
| `pt-snap-mcp` | 启动 MCP 服务器以支持 Agent 集成 |

## MCP 服务器

`pt-snap-cli` 提供了 MCP(Model Context Protocol)服务器,使 AI Agent 能够以编程方式与 PyTorch 内存快照交互。

```bash
# 启动 MCP 服务器
pt-snap-mcp
```

服务器暴露以下工具:

| 工具 | 说明 |
|------|------|
| `get_focus` | 获取当前分析焦点 |
| `set_focus` | 设置焦点到指定数据库和设备 |
| `list_templates` | 列出可用的查询模板 |
| `get_template_info` | 获取模板详情和参数 |
| `execute_query` | 对焦点数据库执行查询模板 |

详见 [MCP 指南](docs/zh/mcp.md)。

## 文档

Expand All @@ -43,6 +65,7 @@ pt-snap query --template-use leak_detection --params '{"min_size": 1024}'
| 入门指南 | [Quick Start](docs/zh/quickstart.md) |
| Focus 管理 | [Focus Management](docs/zh/focus-management.md) |
| 运行查询 | [Querying](docs/zh/querying.md) |
| MCP 服务器 | [MCP 指南](docs/zh/mcp.md) |
| 数据库格式 | [SnapshotDB Schema](docs/zh/database.md) |
| Python API | [ResultMapper API](docs/zh/result-mapper-api.md) |

Expand All @@ -65,6 +88,7 @@ pt-snap-cli/
│ ├── cli.py # CLI 入口
│ ├── context.py # 数据库连接管理器
│ ├── config.py # 焦点管理
│ ├── api.py # Python API 层
│ ├── query/
│ │ ├── builder.py # 查询构建器
│ │ ├── executor.py # 查询执行器
Expand All @@ -73,7 +97,8 @@ pt-snap-cli/
│ │ ├── condition.py # 查询条件
│ │ ├── config.py # 查询配置
│ │ └── templates/ # 查询模板
│ └── models/ # 数据模型
│ ├── models/ # 数据模型
│ └── mcp/ # MCP 服务器(Agent 集成)
├── tests/ # 测试文件
├── examples/ # 示例数据
└── docs/ # 文档
Expand Down
78 changes: 78 additions & 0 deletions docs/en/mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# MCP Server

[中文](../zh/mcp.md) | English

`pt-snap-cli` provides an MCP (Model Context Protocol) server that allows AI agents to interact with PyTorch memory snapshots programmatically.

## Installation

```bash
pip install -e .
```

The MCP server is installed as part of the core package.

## Starting the Server

```bash
pt-snap-mcp
```

This starts a FastMCP server that exposes tools for analyzing PyTorch memory snapshots.

## Available Tools

| Tool | Description |
|------|-------------|
| `get_focus` | Get the current analysis focus (database path, device ID, source) |
| `set_focus` | Set focus to a database and optional device. Use before running queries. |
| `list_templates` | List available query templates, optionally filtered by category |
| `get_template_info` | Get detailed information about a template including parameters |
| `execute_query` | Execute a query template against the focused database |

## Available Resources

| Resource | Description |
|----------|-------------|
| `focus://current` | Current analysis focus state |

## Available Prompts

| Prompt | Description |
|--------|-------------|
| `analyze_memory_leaks` | Generate a prompt template for analyzing memory leaks |

## Typical Workflow

1. Call `set_focus` with `db_path` to point to a snapshot file
2. Call `list_templates` to discover available queries
3. Call `get_template_info` with a template name to see its parameters
4. Call `execute_query` with the template name and parameters

## Example Usage

```python
# Set focus to a snapshot
set_focus(db_path="/path/to/snapshot.db", device_id=0)

# List templates
list_templates()
# Returns: [{"name": "leak_detection", "description": "...", ...}, ...]

# Get template details
get_template_info("leak_detection")
# Returns: {"name": "leak_detection", "parameters": [...], ...}

# Run a query
execute_query("leak_detection", params={"min_size": 1024})
# Returns: {"total": 5, "returned": 5, "rows": [...]}
```

## CLI Commands

The MCP entry point is declared in `pyproject.toml`:

```toml
[project.scripts]
pt-snap-mcp = "pt_snap_cli.mcp.server:main"
```
1 change: 1 addition & 0 deletions docs/en/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,4 +54,5 @@ pt-snap query --template-use block --device 1 --state 1

- [Focus Management](focus-management.md) — Learn how to manage database and device focus across projects and sessions
- [Querying](querying.md) — Full guide to all query templates, parameters, and output
- [MCP Server](mcp.md) — Use the MCP server for AI agent integration
- [Database Schema](database.md) — Understand the SnapshotDB format
78 changes: 78 additions & 0 deletions docs/zh/mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# MCP 服务器

[English](../en/mcp.md) | 中文

`pt-snap-cli` 提供了 MCP(Model Context Protocol)服务器,使 AI Agent 能够以编程方式与 PyTorch 内存快照交互。

## 安装

```bash
pip install -e .
```

MCP 服务器作为核心包的一部分自动安装。

## 启动服务器

```bash
pt-snap-mcp
```

这将启动一个 FastMCP 服务器,暴露用于分析 PyTorch 内存快照的工具。

## 可用工具

| 工具 | 说明 |
|------|------|
| `get_focus` | 获取当前分析焦点(数据库路径、设备 ID、来源) |
| `set_focus` | 设置焦点到指定数据库和可选设备。运行查询前使用。 |
| `list_templates` | 列出可用的查询模板,可按类别筛选 |
| `get_template_info` | 获取模板详情,包括参数信息 |
| `execute_query` | 对焦点数据库执行查询模板 |

## 可用资源

| 资源 | 说明 |
|------|------|
| `focus://current` | 当前分析焦点状态 |

## 可用提示词

| 提示词 | 说明 |
|--------|------|
| `analyze_memory_leaks` | 生成用于分析内存泄漏的提示词模板 |

## 典型工作流

1. 调用 `set_focus` 并传入 `db_path` 指向快照文件
2. 调用 `list_templates` 发现可用查询
3. 调用 `get_template_info` 查看模板参数
4. 调用 `execute_query` 执行查询

## 使用示例

```python
# 设置焦点到快照文件
set_focus(db_path="/path/to/snapshot.db", device_id=0)

# 列出模板
list_templates()
# 返回: [{"name": "leak_detection", "description": "...", ...}, ...]

# 获取模板详情
get_template_info("leak_detection")
# 返回: {"name": "leak_detection", "parameters": [...], ...}

# 运行查询
execute_query("leak_detection", params={"min_size": 1024})
# 返回: {"total": 5, "returned": 5, "rows": [...]}
```

## CLI 命令

MCP 入口点在 `pyproject.toml` 中声明:

```toml
[project.scripts]
pt-snap-mcp = "pt_snap_cli.mcp.server:main"
```
1 change: 1 addition & 0 deletions docs/zh/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,4 +54,5 @@ pt-snap query --template-use block --device 1 --state 1

- [Focus 管理](focus-management.md) — 学习如何在多个项目和会话之间管理数据库和设备焦点
- [运行查询](querying.md) — 所有查询模板、参数和输出的完整指南
- [MCP 服务器](mcp.md) — 使用 MCP 服务器进行 AI Agent 集成
- [数据库格式](database.md) — 了解 SnapshotDB 格式
4 changes: 3 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ classifiers = [
]

dependencies = [
"mcp>=1.0.0",
"typer>=0.9.0",
"pyyaml>=6.0",
"jinja2>=3.0.0",
Expand All @@ -50,6 +51,7 @@ rag = [

[project.scripts]
pt-snap = "pt_snap_cli.cli:_safe_call"
pt-snap-mcp = "pt_snap_cli.mcp.server:main"

[tool.setuptools.packages.find]
where = ["src"]
Expand Down Expand Up @@ -92,4 +94,4 @@ exclude_lines = [
fail_under = 0

[tool.coverage.xml]
output = "coverage.xml"
output = "coverage.xml"
Loading
Loading