STARWARCLOUD STARWAR.AI
返回市场
后台-MCP服务器

后台-MCP服务器

作者：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

设置

  1. 克隆仓库：

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

  2. 安装依赖：

    yarn install

  3. 构建并验证项目：

    yarn build:validate

    或手动构建：

    yarn build

  4. （可选）运行依赖分析：

    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

添加新工具

  1. 在 src/tools/ 中创建一个新的工具文件
  2. 使用 @Tool 装饰器实现工具类
  3. 从 src/tools/index.ts 导出
  4. 定义 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: 结果 });
  }
}

贡献

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

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

许可

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

支持及文档

相关项目

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client(
  {
    name: 'example-client',
    version: '1.0.0',
  },
  {
    capabilities: {},
  }
);

// 连接到 Backstage MCP 服务器
await client.connect(new StdioServerTransport(process));

// 列出可用工具
const tools = await client.request({ method: 'tools/list' });
console.log('可用工具：', tools);

// 调用工具
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'get_entity_by_ref',
    arguments: {
      entityRef: 'component:default/my-component',
    },
  },
});
console.log('工具结果：', result);