backstage-mcp-server

Backstage MCP 服务

一个面向 Backstage 软件目录的类型安全 Model Context Protocol 服务，基于已发布的 @coderrob/mcp-kernel 运行时构建。

它通过 stdio 提供 32 个目录工具，使用 Backstage 官方目录客户端，支持轮换 bearer 凭据，并提供黑盒 SDK 和 MCP Inspector 验证。

你将获得

能力	实现
目录发现	实体查询、引用、祖先关系、分类和源位置
目录操作	添加位置、刷新实体、移除实体或位置，以及验证描述符
类型安全	Zod schema 推断处理程序输入，并生成兼容 MCP 的 JSON Schema
运行时策略	超时、调用方作用域、按主体限流、带标签的缓存和失效处理
安全操作	MCP 注解可区分只读、修改、幂等和破坏性工具
生产边界	官方 Backstage CatalogClient、经过身份验证的 fetch、已脱敏的 stderr 日志
验证	按文件覆盖率、SDK stdio 冒烟测试、逐一执行所有工具，以及 MCP Inspector

快速开始

1. 安装并构建

要求：

• Node.js 24.15 或更高版本
• Corepack
• 可访问的 Backstage 后端和已获认可的外部访问 bearer token

corepack enable
corepack yarn install --immutable
corepack yarn build

Yarn 版本来自 package.json 中的 packageManager 字段；请使用 corepack yarn，以确保本地和 CI 行为一致。

2. 配置 Backstage

设置后端根 URL 或完整的目录插件 URL，并选择一种凭据来源：

export BACKSTAGE_BASE_URL=https://backstage.example.com
export BACKSTAGE_TOKEN=your-token

对于外部轮换的凭据，请改为指向一个 token 文件：

export BACKSTAGE_BASE_URL=https://backstage.example.com
export BACKSTAGE_TOKEN_FILE=/run/secrets/backstage-token

如果两个变量都存在，BACKSTAGE_TOKEN_FILE 优先，并且每次发送请求时都会重新读取该文件。可选的 LOG_LEVEL=debug 可启用诊断日志。日志始终写入 stderr，因为 stdout 用于 MCP 协议通信。

3. 启动 stdio 服务

corepack yarn start

该进程会等待 MCP 客户端通过 stdin/stdout 连接。要针对真实部署进行只读检查，请运行 corepack yarn test:live；请参阅真实 Backstage 部署验证。

连接 MCP 客户端

构建完成后，使用绝对路径配置 stdio 客户端：

{
  "mcpServers": {
    "backstage": {
      "command": "node",
      "args": ["/absolute/path/to/backstage-mcp-server/dist/cli.cjs"],
      "env": {
        "BACKSTAGE_BASE_URL": "https://backstage.example.com",
        "BACKSTAGE_TOKEN": "your-token"
      }
    }
  }
}

全局安装后，将 backstage-mcp-server 用作命令。不要将凭据放入已提交的客户端配置中；请在可用时使用客户端的密钥或环境变量机制。

工具目录

已提交的 tools-manifest.json 根据运行时定义生成，是机器可读的事实来源。

类别	工具
实体发现	get_entities、get_entities_by_query、get_entities_by_refs、get_entity_by_ref、get_entity_ancestors、get_entity_facets
位置发现	get_location_by_entity、get_location_by_ref
验证	validate_entity
目录变更	add_location、refresh_entity
破坏性变更	remove_entity_by_uid、remove_location_by_id

get_entities.filter 遵循 Backstage 的键值模型：同一条记录中的键是 AND 条件，同一键的值是 OR 条件，多条记录是 OR 组。

{
  "filter": {
    "kind": ["Component", "API"],
    "metadata.namespace": "default"
  }
}

这会选取 default 命名空间中的 Component 或 API。Backstage 集成指南记录了每种工具到客户端的映射、游标行为、身份验证、权限和错误转换。

工作原理

1. MCP 客户端启动打包后的 CLI，并通过 stdio 交换 JSON-RPC。
2. 已发布的 MCP Kernel 会验证并编译不可变的功能定义。
3. Zod 会在中间件、授权、缓存、速率限制和超时策略运行之前验证输入。
4. Backstage 工具会从其应用上下文调用类型化的 Catalog 契约。
5. 适配器会将 HTTP 行为委托给官方 Backstage CatalogClient，并在 fetch 边界注入 bearer token。
6. 结果以 MCP 文本和结构化内容的形式返回；预期的失败会使用稳定的错误代码和安全的详细信息。

已发布的 @coderrob/mcp-kernel 包负责协议注册、生命周期、策略、传输、测试支持和符合协议安全要求的日志记录。本仓库仅负责 Backstage 应用和 Catalog 集成。依赖边界请参阅当前架构概述。

MCP Kernel 依赖项

通用服务编写、生命周期、策略、传输、结果、测试支持和日志记录的相关文档位于 @coderrob/mcp-kernel 仓库。此包会重新导出 kernel API 以保持兼容，但新的通用使用方应直接安装并导入 @coderrob/mcp-kernel。

要为 Catalog 添加功能，请遵循添加 Backstage MCP 工具。

验证

运行常规贡献者检查：

corepack yarn lint
corepack yarn typecheck
corepack yarn architecture:check
corepack yarn knip
corepack yarn test
corepack yarn test:shell

对于 MCP、工具、适配器或打包相关变更，还应运行：

corepack yarn test:mcp
corepack yarn manifest:check

test:mcp 会运行契约测试、构建发行包、通过官方 SDK 客户端在 stdio 上启动 dist/cli.cjs，针对确定性且经过身份验证的 Catalog 存根调用每个已注册工具，并执行独立的 MCP Inspector 检查。它不会通过直接调用处理程序或 HTTP 请求来绕过服务。

请参阅仓库工具，了解每条命令的用途和副作用；有关确切的黑盒边界，请参阅MCP 端到端测试。

文档

从文档中心中选择一个方向：

• 使用：Backstage 集成和端到端测试
• 开发：仓库工具、代码质量和添加工具
• 了解：架构概览、ADR、历史分析和实施计划
• 维护：依赖管理

许可证

GPL-3.0。请参阅 LICENSE。

精选知识和技能

Backstage 知识库维护经过分类的文章、具名来源引用和 schema.org 元数据。.agents/skills 中的仓库技能支持目录查询、实体维护和 MCP 开发。

19 个上下文查询工具涵盖名称、System 和 Domain 内容、Group、所有权、依赖项、API、注释和孤立实体。请参阅查询约定和示例，其中包括分页、歧义处理和工作量限制。