后台MCP服务器
一个可用于生产的企业级模型上下文协议（MCP）服务器，它公开Backstage Catalog API作为大型语言模型（LLM）的工具。具有全面的操作透明度、跨平台兼容性和自动错误恢复功能。
这允许LLM通过具有企业级可靠性和监控的标准化协议与Backstage软件目录进行交互。
特性
- 完整目录API覆盖范围：将所有主要Backstage Catalog API端点作为MCP工具实施
- 动态工具加载：自动从代码库中发现和注册工具
- 类型安全：通过Zod模式验证完全支持TypeScript
- 生产就绪：通过适当的错误处理和日志记录实现可靠性
- 企业级：具有运营透明度和监控的跨平台支持
- 操作透明度：全面的审计跟踪、运行状况监控和自动错误恢复
- 跨平台兼容性：在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 18+
- Yarn 4.4.0+（配置为packageManager）
- 访问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访问的承载令牌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服务器将启动并监听stdin/stdout上的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进行交互：
User: "Show me all the services in the catalog"
LLM: Uses get_entities tool with appropriate filters
User: "What's the location for the user-service entity?"
LLM: Uses get_location_by_entity toolapi参考
刀具参数
所有工具都接受由其Zod模式定义的参数。实体参考可以提供为：
- 字符串：
"component:default/user-service" - 对象：
{ kind: "component", namespace: "default", name: "user-service" }
响应格式
所有工具都返回具有以下结构的JSON响应：
{
"status": "success" | "error",
"data":
}发展
项目结构
src/
├── api/ # Backstage API client
├── auth/ # Authentication and security
├── cache/ # Caching layer
├── decorators/ # Tool decorators
├── tools/ # MCP tool implementations
├── types/ # Type definitions and constants
├── utils/ # Utility functions
└── index.ts # Main server entry point
scripts/
├── validate-build.sh # Build validation with operational transparency
├── dependency-manager.sh # Dependency analysis with cross-platform support
├── deps-crossplatform.sh # Cross-platform dependency operations
├── monitor.sh # System monitoring and health checks
└── deps.sh # Legacy dependency scripts
docs/
├── OPERATIONAL_TRANSPARENCY.md # Operational transparency documentation
├── DEPENDENCY_GUIDE.md # Dependency management guide
├── EDGE_CASES_SUMMARY.md # Edge cases and cross-platform considerations
└── BUILD_SETUP.md # Build system documentation建筑
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构建包括一个用于全局npm安装的shebang
- 摇树优化：删除较小捆绑包大小的未使用代码
- 跨平台构建：跨Windows、macOS和Linux的一致构建
- 构建验证：具有操作透明度的自动验证
- 错误恢复：生成失败时自动回滚
NPM出版
该包已配置为通过以下方式发布到NPM：
npm publish发布后，可以全局安装服务器：
npm install -g @coderrob/backstage-mcp-server
backstage-mcp-server运营透明度和企业特征
此MCP服务器包括全面的运营透明度和企业级功能：
监测和健康检查
- 实时健康监测：持续的系统健康跟踪
- 资源使用情况跟踪：内存、磁盘和CPU监控
- SLA跟踪：服务水平协议监控和报告
- 自动警报：可配置的紧急情况警报
构建和依赖管理
- 跨平台兼容性：跨Windows、macOS和Linux的一致操作
- 相关性分析：全面的依赖冲突检测和解决
- 构建验证：具有回滚功能的自动构建验证
- 审计跟踪：完成所有操作的审计日志记录
错误恢复和弹性
- 网络弹性：网络操作的自动重试逻辑
- 构建回滚：生成失败时自动回滚
- 依赖性备份/恢复：依赖关系的备份和恢复功能
- 结构化日志记录：具有完整上下文的JSON格式日志
使用示例
健康监测
# Check system health
yarn monitor:health
# View monitoring dashboard
yarn monitor:dashboard
# Check alerts
yarn monitor:alerts依赖管理
# Analyze dependencies
yarn deps:analyze
# Validate dependency health
yarn deps:validate
# Cross-platform dependency operations
yarn deps:crossplatform构建验证
# Comprehensive build validation
yarn build:validate
# Development build
yarn build:dev
# Watch mode
yarn build:watch测试
yarn test掉毛
yarn lint添加新工具
- 在中创建新的工具文件
src/tools/ - 使用实现工具类
@Tool装饰器 - 出口自
src/tools/index.ts - 为参数定义Zod模式
例子：
@Tool({
name: 'my_tool',
description: 'Description of my tool',
paramsSchema: z.object({ param: z.string() }),
})
export class MyTool {
static async execute({ param }, context) {
// Implementation
return JsonToTextResponse({ status: 'success', data: result });
}
}贡献
我们欢迎捐款！请参阅我们的贡献指南，并确保所有更改都包括适当的测试。
- 分叉存储库
- 创建要素分支
- 通过全面测试进行更改
- 运行完整的验证套件：
yarn build:validate && yarn deps:analyze - 提交拉取请求
许可证
此项目根据GPLv3许可证获得许可-请参阅 许可证 文件以获取详细信息。
支持和文档
相关项目
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
const client = new Client(
{
name: 'example-client',
version: '1.0.0',
},
{
capabilities: {},
}
);
// Connect to the Backstage MCP server
await client.connect(new StdioServerTransport(process));
// List available tools
const tools = await client.request({ method: 'tools/list' });
console.log('Available tools:', tools);
// Call a tool
const result = await client.request({
method: 'tools/call',
params: {
name: 'get_entity_by_ref',
arguments: {
entityRef: 'component:default/my-component',
},
},
});
console.log('Tool result:', result);