Linearb MCP Server

LinearB MCP服务器（只读）

模型上下文协议（MCP）服务器，用于查看和查询LinearB API数据。这是一个 只读的 服务器，提供对LinearB信息的安全访问，而无需修改数据。

功能（只读）

• 部署：列出并查看部署信息
• 团队：使用V2 API搜索和查看团队信息
• 用户：搜索和查看用户信息
• 服务：检索服务信息
• 事件：查看和搜索事件信息
• 指标：查询和导出指标数据
• 健康检查：监视API运行状况

备注：这是一个只读服务器。为了安全起见，所有创建、更新和删除操作都被禁用。

安装

1. 克隆此存储库
2. 创建并激活虚拟环境（推荐）：

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

1. 确保pip可用：

   python3 -m ensurepip --upgrade

1. 安装依赖项：

   python3 -m pip install -r requirements.txt

配置

API密钥设置

将LinearB API键设置为环境变量：

export LINEARB_API_KEY="your-api-key-here"

或者，您可以在 .env 文件：

LINEARB_API_KEY=your-api-key-here

MCP配置

将此服务器添加到MCP配置文件中(mcp.json):

{
  "mcpServers": {
    "linearb": {
      "command": "python",
      "args": ["path/to/Linearb_mcp/server.py"],
      "env": {
        "LINEARB_API_KEY": "your-api-key-here"
      }
    }
  }
}

可用工具

发现服务

• discover_api：获取全面的API信息和可用的端点
• get_endpoint_details：获取有关特定API终结点的详细信息
• get_api_categories：获取按类别组织的API终结点
• get_usage_examples：获取API端点的使用示例
• get_documentation_files：列出可用的文档文件

指标发现

• get_supported_metrics：获取所有支持的LinearB指标的全面列表
• get_metrics_by_category：获取按类别组织的指标（cycle_time、pull_requests、commits等）
• search_metrics：使用过滤选项按名称或描述搜索指标
• get_metric_examples：获取度量查询的实际使用示例

团队探索

• get_active_teams：获取所有活跃团队的综合列表以供分析
• get_teams_by_type：按类型（工程或质量保证）筛选团队
• get_comparable_teams：获得可以比较的工程团队（不包括QA团队）
• search_teams_by_focus：按重点领域、名称或描述搜索团队

部署（只读）

• list_deployments：列出具有筛选选项的部署

Teams（V2 API-只读）

• search_teams_v2：使用V2 API进行分页的搜索团队

用户（只读）

• search_users：使用分页和筛选搜索用户

服务（只读）

• get_services：获取所有服务，可选择按存储库筛选
• get_service：通过ID获取特定服务

事件（只读）

• get_incident：按提供商ID获取特定事件
• search_incidents：使用筛选功能搜索事件

指标（只读）

• post_metrics：从LinearB查询度量数据
• export_metrics：以CSV或JSON格式导出指标数据

健康

• health_check：检查API运行状况

使用示例

发现服务

# Discover all available API endpoints
api_info = await discover_api()

# Get detailed information about a specific endpoint
endpoint_details = await get_endpoint_details("/api/v1/deployments", "GET")

# Get endpoints organized by categories
categories = await get_api_categories()

# Get usage examples for a specific category
examples = await get_usage_examples(category="deployments")

# Get usage examples for a specific tool
tool_examples = await get_usage_examples(tool_name="list_deployments")

# List available documentation files
docs = await get_documentation_files()

指标发现

# Get all supported metrics with details
all_metrics = await get_supported_metrics()

# Get metrics by category
cycle_time_metrics = await get_metrics_by_category("cycle_time")
pr_metrics = await get_metrics_by_category("pull_requests")

# Search for specific metrics
time_metrics = await search_metrics("time", has_aggregation=True)
commit_metrics = await search_metrics("commit", category="commits")

# Get practical usage examples
metric_examples = await get_metric_examples()

团队探索

# Get all active teams
all_teams = await get_active_teams()

# Get only engineering teams for comparison
engineering_teams = await get_teams_by_type("engineering")
comparable_teams = await get_comparable_teams()

# Get QA teams (tracked separately)
qa_teams = await get_teams_by_type("qa")

# Search teams by focus area
integration_teams = await search_teams_by_focus("integration", comparable_only=True)
automation_teams = await search_teams_by_focus("automation", team_type="qa")

列出最近的部署

# List the 20 most recent deployments
deployments = await list_deployments(limit=20, sort_dir="desc")

查看部署详细信息

# List deployments with filtering
deployments = await list_deployments(
    repository_id=12345,
    after="2023-01-01",
    limit=20
)

查询指标

# Get cycle time metrics for the last month
metrics = await post_metrics(
    group_by="organization",
    roll_up="1w",
    requested_metrics=[
        {"name": "branch.computed.cycle_time", "agg": "p75"},
        {"name": "branch.time_to_pr", "agg": "p50"},
        {"name": "pr.merged"}
    ],
    time_ranges=[
        {"after": "2023-12-01", "before": "2023-12-31"}
    ]
)

# Use metrics discovery to find available metrics
supported_metrics = await get_supported_metrics()
cycle_metrics = await get_metrics_by_category("cycle_time")

搜索团队（V2 API）

# Search for teams with V2 API
teams = await search_teams_v2(
    search_term="backend",
    page_size=20,
    offset=0
)

# Search teams with filtering
teams = await search_teams_v2(
    search_term="backend",
    page_size=20,
    nonmerged_members_only=False
)

搜索用户

# Search for users
users = await search_users(
    search_by_field="name",
    search_term="john",
    page_size=25,
    order_by="name",
    order_dir="ASC"
)

# Search users with advanced filtering
users = await search_users(
    search_by_field="name",
    search_term="john",
    user_role="editor",
    order_by="name",
    order_dir="ASC"
)

错误处理

服务器包括全面的错误处理：

• HTTP错误：正确处理带有详细消息的API响应错误
• 网络错误：妥善处理连接问题
• 验证错误：带有明确错误消息的输入验证
• 日志记录：用于调试和监控的结构化日志记录

安全功能

• 环境变量：API键是从环境变量加载的
• 输入验证：在进行API调用之前验证所有输入
• 速率限制：遵守API限制，包括正确的超时处理
• 安全标头：为API请求包含正确的HTTP标头

发展

运行服务器

python3 server.py

测试

快速测试

运行测试脚本以验证安装：

python3 test_server.py

这将测试基本功能。请注意，如果没有有效的API密钥，您将看到403个错误，这是预期的。

手动测试

您可以使用MCP客户端或直接导入函数来测试单个工具：

# Test import
python3 -c "import server; print('Server imports successfully')"

探索服务演示

运行发现服务演示以查看所有功能的运行情况：

python3 demo_discovery.py

此演示展示了：

• API端点发现和分类
• 详细参数信息
• 使用示例和代码片段
• 可用文档文件
• 交互式探索功能

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

API文档

有关LinearB API端点的详细信息，请参阅 LinearB API文档.

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

1. 检查 LinearB API文档
2. 查看服务器日志以了解错误详细信息
3. 在此存储库中打开问题

发现服务功能

LinearB MCP服务器包括一项全面的发现服务，可帮助MCP客户了解API并与之交互：

API发现

• 端点发现：自动从OpenAPI规范中查找所有可用的API终结点
• 参数信息：提供详细的参数信息，包括类型、要求和约束
• 响应模式：显示预期的响应格式和结构
• 请求示例：包括示例请求和有效载荷

自我记录

• 工具映射：将API端点映射到MCP工具名称以便于参考
• 类别式组织：按功能类别（部署、团队、指标等）对端点进行分组
• 使用示例：为每个工具提供代码示例和最佳实践
• 文档文件：列出可用的PDF文档文件

交互式探索

使用发现工具来探索API：

# Get overview of all available endpoints
api_overview = await discover_api()

# Explore endpoints by category
categories = await get_api_categories()

# Get detailed information about a specific endpoint
endpoint_info = await get_endpoint_details("/api/v1/deployments", "GET")

# Find usage examples
examples = await get_usage_examples(tool_name="list_deployments")

活跃团队参考

服务器包括按类型组织的7个活跃团队的综合参考：

工程团队（可比）

• 分析 （Aly）-分析和数据工程团队
• CFD（泰坦） （CFD）-CFD Titans工程团队
• 核心CRM （CC）-核心CRM平台团队
• 集成（协同） （I） 集成与协同团队
• 媒体 （Med）-媒体和内容管理团队
• 新生 （S） -新生开发团队

QA团队（单独跟踪）

• QA自动化 （QA）-质量保证和测试自动化团队

备注：工程团队可以在指标分析中进行比较。QA团队被单独跟踪，不应与工程团队进行比较。

支持的指标参考

该服务器包括22个支持的LinearB指标的综合参考，分为7类：

度量类别

• 周期时间 （5个指标）：使用p75/p50/avg聚合的完整开发周期指标
• 拉取请求 （6个指标）：公关规模、评论、合并模式
• 承诺 （4个指标）：代码更改、返工、重构分析
• 发布 （1公制）：释放计数
• 活动 （1个指标）：开发人员活动跟踪
• 分支 （2个指标）：分支状态监控
• 事件 （2个指标）：MTTR和事件解决

关键指标示例

• branch.computed.cycle_time -全周期时间（支持p75、p50、avg）
• branch.time_to_pr -编码时间（支持p75、p50、avg）
• pr.merged.size -PR大小分析（支持p75、p50、avg）
• commit.activity.rework.count -代码返工跟踪
• pm.mttr -平均修复时间

使用指标发现工具探索所有可用的指标及其使用模式。

启用写入操作

如果需要启用创建、更新和删除操作，可以在中取消注释相关函数 server.py.查找标记为的部分：

# =============================================================================
# WRITE OPERATIONS DISABLED - READ-ONLY MCP SERVER
# =============================================================================

⚠️ 警告：启用写操作允许服务器修改LinearB帐户中的数据。谨慎使用并确保适当的访问控制。

更新日志

v1.2.0版本

• 突破性变化：为了安全起见，已转换为只读服务器
• 禁用所有创建、更新和删除操作
• 更新Teams API以使用V2端点（仅限读取操作）
• 增加了用户API支持（仅限搜索操作）
• 新：全面的指标发现系统，支持22个指标
• 新：4个指标发现工具（get_supported_metrics、search_metrics等）
• 新：按7个类别组织的指标（循环时间、pull_requests、commits等）
• 新：7个团队的主动团队发现系统（6个工程团队+1个质量保证团队）
• 新：4个团队发现工具（get_active_teams、get_parable_teams等）
• 新：具有可比性规则的团队类型分类（工程与质量保证）
• 新：指标和团队查询的实际使用示例
• 全面的发现服务，共13个工具
• OpenAPI规范集成用于自动端点发现
• 带有使用示例和参数详细信息的自文档化API
• 具有发现服务验证功能的增强测试套件
• 更新以匹配最新的OpenAPI规范

v1.1.0版本

• 添加了5个新工具的全面发现服务
• OpenAPI规范集成用于自动端点发现
• 带有使用示例和参数详细信息的自文档化API
• 具有发现服务验证功能的增强测试套件
• 通过发现服务示例改进文档

v1.0.0

• 带有完整LinearB API支持的初始版本
• 全面的错误处理和记录
• 通过环境变量配置提高安全性
• 所有函数的类型提示和文档