后台-MCP服务器

Name: 后台-MCP服务器
Author: Coderrob

作者：Coderrob2 星标更新：2025-11-18

安装使用来源：spider==github.com

项目介绍

Backstage MCP 服务器

这是一个生产就绪的企业级模型上下文协议（MCP）服务器，它将 Backstage 目录 API 作为大型语言模型（LLMs）的工具。该服务器具有全面的操作透明性、跨平台兼容性和自动错误恢复功能。

这使得 LLM 可以通过标准化协议与 Backstage 软件目录进行交互，并具备企业级的可靠性和监控功能。

特性

完整的目录 API 支持：实现所有主要的 Backstage 目录 API 端点作为 MCP 工具
动态工具加载：自动发现并注册代码库中的工具
类型安全：支持完整的 TypeScript 和 Zod 模式验证
生产就绪：构建时具备适当的错误处理和日志记录，确保可靠性
企业级：跨平台支持，具备操作透明性和监控功能
操作透明性：全面的审计跟踪、健康监控和自动错误恢复
跨平台兼容性：在 Windows、macOS 和 Linux 上无缝运行
高级构建系统：双格式构建（ESM/CommonJS），包含最小化和树摇优化

可用工具

实体管理

get_entity_by_ref - 根据引用获取单个实体
get_entities - 使用过滤器查询实体
get_entities_by_query - 具有排序功能的高级实体查询
get_entities_by_refs - 根据引用获取多个实体
get_entity_ancestors - 获取实体祖先树
get_entity_facets - 获取实体面统计信息

位置管理

get_location_by_ref - 根据引用获取位置
get_location_by_entity - 获取与实体关联的位置
add_location - 创建新位置
remove_location_by_id - 删除位置

实体操作

refresh_entity - 触发实体刷新
remove_entity_by_uid - 根据 UID 删除实体
validate_entity - 验证实体结构

安装

前提条件

Node.js 118+
Yarn 4.4.0+（配置为包管理器）
访问 Backstage 实例
跨平台支持：Windows（使用 MSYS/Cygwin）、macOS 或 Linux

设置

克隆仓库：

git clone https://github.com/Coderrob/backstage-mcp-server.git
cd backstage-mcp-server

安装依赖：
```
yarn install
```
构建并验证项目：
```
yarn build:validate
```
或手动构建：
```
yarn build
```
（可选）运行依赖分析：
```
yarn deps:analyze
```

配置

服务器需要环境变量来访问 Backstage API：

必要的环境变量

BACKSTAGE_BASE_URL - Backstage 实例的基本 URL（例如，https://backstage.example.com）

认证配置

选择以下认证方法之一：

BACKSTAGE_TOKEN - API 访问的 Bearer 令牌
BACKSTAGE_CLIENT_ID, BACKSTAGE_CLIENT_SECRET, BACKSTAGE_TOKEN_URL - OAuth 凭证
BACKSTAGE_API_KEY - API 密钥认证
BACKSTAGE_SERVICE_ACCOUNT_KEY - 服务账户密钥

示例配置

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

使用

启动服务器

yarn start

服务器将启动并监听标准输入/输出上的 MCP 协议消息。

与 MCP 客户端集成

此服务器设计用于与兼容 MCP 的客户端一起工作。配置您的 MCP 客户端以使用此服务器：

{
  "mcpServers": {
    "backstage": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "BACKSTAGE_BASE_URL": "https://your-backstage-instance.com",
        "BACKSTAGE_TOKEN": "your-backstage-token"
      }
    }
  }
}

在 NPM 发布后进行全局安装：

{
  "mcpServers": {
    "backstage": {
      "command": "backstage-mcp-server",
      "env": {
        "BACKSTAGE_BASE_URL": "https://your-backstage-instance.com",
        "BACKSTAGE_TOKEN": "your-backstage-token"
      }
    }
  }
}

与 LLM 的示例使用

一旦连接，LLM 可以使用自然语言与 Backstage 进行交互：

用户："显示目录中的所有服务"

LLM：使用带有适当过滤器的 get_entities 工具

用户："用户服务实体的位置是什么？"

LLM：使用 get_location_by_entity 工具

API 参考

工具参数

所有工具接受由其 Zod 模式定义的参数。实体引用可以提供为：

字符串："component:default/user-service"
对象：{ kind: "component", namespace: "default", name: "user-service" }

响应格式

所有工具返回具有以下结构的 JSON 响应：

{
  "status": "success" | "error",
  "data": <结果>
}

开发

项目结构

src/
├── api/           # Backstage API 客户端
├── auth/          # 认证和安全性
├── cache/         # 缓存层
├── decorators/    # 工具装饰器
├── tools/         # MCP 工具实现
├── types/         # 类型定义和常量
├── utils/         # 工具函数
└── index.ts       # 主服务器入口点

scripts/
├── validate-build.sh    # 带有操作透明性的构建验证
├── dependency-manager.sh # 带有跨平台支持的依赖分析
├── deps-crossplatform.sh         # 跨平台依赖操作
├── monitor.sh                    # 系统监控和健康检查
└── deps.sh                       # 遗留依赖脚本

docs/
├── OPERATIONAL_TRANSPARENCY.md   # 操作透明文档
├── DEPENDENCY_GUIDE.md          # 依赖管理指南
├── EDGE_CASES_SUMMARY.md        # 边缘情况和跨平台考虑
└── BUILD_SETUP.md               # 构建系统文档

构建

yarn build

构建系统使用 Rollup 创建针对 CommonJS 和 ESM 格式的优化捆绑包：

dist/index.cjs - 带有 shebang 的 CommonJS 捆绑包，用于 CLI 使用
dist/index.mjs - ESM 捆绑包
dist/index.d.ts - TypeScript 声明

构建特性

双格式支持：生成 CommonJS 和 ESM 输出以获得最大兼容性
最小化：所有输出都使用 Terser 进行生产使用的最小化
源映射：包括用于调试的源映射
TypeScript 声明：捆绑 .d.ts 文件以确保类型安全
全局安装：CommonJS 构建包含 shebang 以便于全局 npm 安装
树摇：移除未使用的代码以减小捆绑包大小
跨平台构建：在 Windows、macOS 和 Linux 上一致的构建
构建验证：带操作透明性的自动化构建验证
错误恢复：构建失败时的自动回滚

NPM 发布

该包已配置为发布到 NPM：

npm publish

发布后，服务器可以全局安装：

npm install -g @coderrob/backstage-mcp-server
backstage-mcp-server

操作透明性及企业特性

此 MCP 服务器包括全面的操作透明性和企业级特性：

监控及健康检查

实时健康监控：持续的系统健康追踪
资源使用追踪：内存、磁盘和 CPU 监控
SLA 跟踪：服务级别协议监控和报告
自动警报：关键条件的可配置警报

构建及依赖管理

跨平台兼容性：在 Windows、macOS 和 Linux 上的一致操作
依赖分析：全面的依赖冲突检测和解决
构建验证：具有回滚能力的自动化构建验证
审计跟踪：所有操作的完整审计日志

错误恢复及弹性

网络弹性：网络操作的自动重试逻辑
构建回滚：构建失败时的自动回滚
依赖备份/恢复：依赖项的备份和恢复功能
结构化日志：带有完整上下文的 JSON 格式日志

使用示例

健康监控

# 检查系统健康
yarn monitor:health

# 查看监控仪表板
yarn monitor:dashboard

# 检查警报
yarn monitor:alerts

依赖管理

# 分析依赖
yarn deps:analyze

# 验证依赖健康
yarn deps:validate

# 跨平台依赖操作
yarn deps:crossplatform

构建验证

# 综合构建验证
yarn build:validate

# 开发构建
yarn build:dev

# 监视模式
yarn build:watch

测试

yarn test

代码检查

yarn lint

添加新工具

在 src/tools/ 中创建一个新的工具文件
使用 @Tool 装饰器实现工具类
从 src/tools/index.ts 导出
定义 Zod 参数模式

示例：

@Tool({
  name: 'my_tool',
  description: '我的工具描述',
  paramsSchema: z.object({ param: z.string() }),
})
export class MyTool {
  static async execute({ param }, context) {
    // 实现
    return JsonToTextResponse({ status: 'success', data: 结果 });
  }
}

贡献

我们欢迎贡献！请参阅我们的贡献指南，并确保所有更改都包含适当的测试。

分叉仓库
创建一个功能分支
进行全面测试的更改
运行完整的验证套件：yarn build:validate && yarn deps:analyze
提交拉取请求

许可

本项目根据 GPLv3 许可证授权 - 详情见 LICENSE 文件。