AI导哈

Sentry MCP CLI工具

轻量级命令行接口工具，为AI助手提供与Sentry Model Context Protocol服务器交互的令牌高效解决方案。

  • by kenneth-liao
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 kenneth-liao/sentry-mcp-cli

使用说明

哨兵MCP CLI

Sentry MCP服务器的轻量级CLI包装器-针对具有渐进式披露的AI助手进行了优化。

概述

此CLI工具为Sentry的模型上下文协议（MCP）服务器提供了一个令牌高效的接口，使AI助手能够通过简单的命令与Sentry进行交互。它实现了 渐进式披露 -默认情况下显示最少的信息（~50-100个令牌），并随需提供详细的文档。

主要特点

  • ✅ 令牌高效：与加载完整的MCP服务器相比，令牌使用量减少了81-90%
  • ✅ 渐进式披露：默认情况下信息最少，根据要求提供详细文档
  • ✅ AI优先设计：默认为JSON输出， --no-interactive 标志，针对代理进行了优化
  • ✅ 所有哨兵工具：访问19个MCP工具（检查、AI调试器、文档、分类、管理）
  • ✅ 智能配置：自动加载 ~/.claude/.env 和 ./.env 使用python dotenv
  • ✅ uv工具：易于安装 uv tool install

代币效率

场景 传统MCP Sentry CLI 节省
发现 ~8000个令牌 ~100个令牌 98.8%
单次操作 ~8500个代币 ~800个代币 90.6%
2次操作 ~9000个令牌 ~1500个令牌 83.3%

安装

先决条件

  • Python 3.13或更高版本
  • 紫外线 包管理器
  • Node.js和npm（用于通过以下方式运行Sentry MCP服务器 npx)
  • Sentry API访问令牌

通过紫外线安装（推荐）

# Install as a uv tool (global installation)
uv tool install git+https://github.com/kenneth-liao/sentry-mcp-cli

# Verify installation
sentry --help
sentry list-tools

安装用于开发

# Clone the repository
git clone https://github.com/kenneth-liao/sentry-mcp-cli
cd sentry-mcp-cli

# Install dependencies with uv
uv sync

# Run commands during development
uv run sentry --help
uv run sentry list-tools

配置

环境变量

CLI从两个位置加载环境变量（按优先级顺序）：

  1. ~/.claude/.env （所有AI助手的用户级配置）
  2. ./.env （项目级配置）

所需配置

创建 ~/.claude/.env 使用您的哨兵证书：

# Create ~/.claude directory if it doesn't exist
mkdir -p ~/.claude

# Create .env file with your credentials
cat > ~/.claude/.env << 'EOF'
# Required: Sentry API Access Token
# Get from: https://sentry.io/settings/account/api/auth-tokens/
SENTRY_ACCESS_TOKEN=sntrys_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional: For self-hosted Sentry instances
SENTRY_HOST=sentry.io

# Optional: Default organization and project
# SENTRY_DEFAULT_ORG=my-org
# SENTRY_DEFAULT_PROJECT=my-project

# Optional: OpenAI API key (enables AI-powered search tools)
# OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
EOF

可选：项目级配置

您还可以创建 .env 项目目录中用于项目特定设置的文件：

# Copy the example file
cp .env.example .env

# Edit with your credentials
nano .env

用法

基本命令

# List all available tools (minimal output)
sentry list-tools

# List tools with JSON output (for AI assistants)
sentry list-tools --json

# Get help for any command
sentry --help
sentry list-tools --help

可用工具（共19个）

# Inspection Tools
sentry find-organizations [--query TEXT] [--json]
sentry find-projects [--org TEXT] [--query TEXT] [--json]
sentry find-teams [--org TEXT] [--query TEXT] [--json]
sentry find-releases [--org TEXT] [--project TEXT] [--query TEXT] [--json]
sentry get-issue-details <issue-id-or-url> [--json]
sentry get-trace-details <trace-id> [--org TEXT] [--json]
sentry get-event-attachment <event-id> [--project TEXT] [--attachment-id TEXT] [--json]
sentry search-events <query> [--org TEXT] [--project TEXT] [--limit N] [--json]  # Requires OpenAI
sentry whoami [--json]

# AI Debugger (Seer)
sentry analyze-issue-with-seer <issue-id-or-url> [--instruction TEXT] [--json]

# Documentation
sentry search-docs <query> [--guide TEXT] [--limit N] [--json]
sentry get-doc <path> [--json]

# Issue Triage
sentry search-issues <query> [--org TEXT] [--project TEXT] [--limit N] [--json]  # Requires OpenAI
sentry update-issue <issue-id> [--status TEXT] [--assignee TEXT] [--json]

# Project & Team Management
sentry create-team <name> [--org TEXT] [--json]
sentry create-project <name> [--team TEXT] [--platform TEXT] [--json]
sentry update-project <project-id> [--name TEXT] [--team TEXT] [--json]
sentry create-dsn <name> [--project TEXT] [--json]
sentry find-dsns [--project TEXT] [--json]

# Meta Commands (Progressive Disclosure)
sentry list-tools [--json]                    # Tier 1: Discovery (~100 tokens)
sentry describe-tool <tool-name> [--json]     # Tier 2: Details (~200 tokens)
sentry tool-schema <tool-name>                # Tier 3: Full schema (~500 tokens)

全球旗帜

所有命令都支持这些全局标志：

--json              # Output as JSON (machine-readable, default for AI assistants)
--verbose / -v      # Increase output verbosity
--quiet / -q        # Minimal output
--no-interactive    # Disable interactive prompts (for automation)
--org TEXT          # Default organization slug (overrides config)
--help              # Show help message

例子

# List organizations in JSON format
sentry find-organizations --json

# Get issue details with verbose output
sentry get-issue-details PROJ-123 --org my-org --verbose --json

# AI-powered search (requires OPENAI_API_KEY in .env)
sentry search-events "database errors in last hour" --org my-org --json

# Find projects in a specific organization
sentry find-projects --org my-org --json

# Get tool documentation
sentry describe-tool get-issue-details

运作原理

建筑

AI Assistant (Claude/etc)
    ↓ runs CLI command
sentry-cli (Python + Typer + Rich)
    ↓ spawns subprocess
npx @sentry/mcp-server@latest
    ↓ stdio transport (JSON-RPC)
MCP Session ←→ Sentry API

渐进式披露

CLI实现了一个三层信息系统：

第1层：发现（~50个代币）

$ sentry list-tools
# Shows: Tool names + one-line descriptions

第2层：工具描述（约200个代币）

$ sentry describe-tool get-issue-details
# Shows: Full description, parameters, examples

第3层：完整架构（约500个令牌）

$ sentry tool-schema get-issue-details
# Shows: Complete JSON schema for the tool

与加载完整的MCP服务器模式相比，这种方法将令牌使用率降低了约90%。

AI驱动的工具

有两个工具需要一个OpenAI API密钥：

  1. search-events -自然语言事件搜索和聚合
  2. search-issues -自然语言问题搜索

设置OpenAI

# Add to ~/.claude/.env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

故障弱化

如果你尝试在没有OpenAI API密钥的情况下使用AI驱动的工具，你会得到一个有用的错误：

Error: This tool requires an OpenAI API key.

Setup:
  1. Get an API key from: https://platform.openai.com/api-keys
  2. Add to ~/.claude/.env:
     OPENAI_API_KEY="sk-xxxxxxxxxxxxx"
  3. Run command again

Alternative: Use 'sentry get-issue-details' for specific issue inspection.

发展

项目结构

sentry-mcp-cli/
├── src/
│   └── sentry_cli/
│       ├── main.py              # Main Typer app + CLI entry point
│       ├── config/
│       │   └── settings.py      # Pydantic settings with dotenv support
│       ├── mcp/
│       │   └── connector.py     # MCP stdio connection manager
│       ├── commands/
│       │   ├── tools.py         # Tool commands
│       │   └── meta.py          # Meta commands (list-tools, etc)
│       └── output/
│           └── formatters.py    # Output formatters
└── tests/

运行测试

# Install dev dependencies
uv sync --extra dev

# Run tests (when implemented)
uv run pytest

实施状态

第一阶段：基础 ✅ 完成

  • [x] 使用uv进行项目设置
  • [x] 加载dotenv的设置类
  • [x] 带stdio子流程的MCP连接器
  • [x] 带有全局标志的主打字机应用程序
  • [x] list-tools 命令

第二阶段：元命令 ✅ 完成

  • [x] describe-tool 命令-详细的工具文档（第2层）
  • [x] tool-schema command-完整JSON模式（第3层）
  • [x] 输出格式化程序（JSON、表格、人类可读）

第3-6阶段：所有工具 📋 计划的

  • []检查工具（查找-*，得到-*哇）
  • []人工智能驱动的工具（搜索-，分析-)
  • []文档工具（搜索文档、获取文档）
  • []分类工具（搜索问题、更新问题）
  • []管理工具（创建-，更新-，查找dsns）

故障排除

未找到命令：哨兵

确保uv的tool bin目录在您的PATH中：

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

缺少SENTRY_ACCESS_TOKEN

# Create ~/.claude/.env with your token
mkdir -p ~/.claude
echo 'SENTRY_ACCESS_TOKEN="sntrys_xxx"' > ~/.claude/.env

MCP服务器无法启动

确保已安装Node.js和npm：

# Check versions
node --version  # Should be v18 or higher
npm --version   # Should be v9 or higher

# If not installed, install Node.js from: https://nodejs.org/

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请打开问题或提交拉取请求。

相关项目

支持

对于问题和疑问：

相关 MCP