backstage-mcp-server by Coderrob - MCP Server

Backstage MCP Server

A production-ready, enterprise-grade Model Context Protocol (MCP) server that exposes the Backstage Catalog API as tools for Large Language Models (LLMs). Features comprehensive operational transparency, cross-platform compatibility, and automated error recovery.

This allows LLMs to interact with Backstage software catalogs through a standardized protocol with enterprise-grade reliability and monitoring.

Features

Complete Catalog API Coverage: Implements all major Backstage Catalog API endpoints as MCP tools
Dynamic Tool Loading: Automatically discovers and registers tools from the codebase
Type-Safe: Full TypeScript support with Zod schema validation
Production Ready: Built for reliability with proper error handling and logging
Enterprise Grade: Cross-platform support with operational transparency and monitoring
Operational Transparency: Comprehensive audit trails, health monitoring, and automated error recovery
Cross-Platform Compatibility: Works seamlessly on Windows, macOS, and Linux
Advanced Build System: Dual-format builds (ESM/CommonJS) with minification and tree-shaking

Available Tools

Entity Management

get_entity_by_ref - Get a single entity by reference
get_entities - Query entities with filters
get_entities_by_query - Advanced entity querying with ordering
get_entities_by_refs - Get multiple entities by references
get_entity_ancestors - Get entity ancestry tree
get_entity_facets - Get entity facet statistics

Location Management

get_location_by_ref - Get location by reference
get_location_by_entity - Get location associated with an entity
add_location - Create a new location
remove_location_by_id - Delete a location

Entity Operations

refresh_entity - Trigger entity refresh
remove_entity_by_uid - Delete entity by UID
validate_entity - Validate entity structure

Installation

Prerequisites

Node.js 18+
Yarn 4.4.0+ (configured as packageManager)
Access to a Backstage instance
Cross-platform support: Windows (with MSYS/Cygwin), macOS, or Linux

Setup

Clone the repository:

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

Install dependencies:
```
yarn install
```
Build and validate the project:
```
yarn build:validate
```
Or build manually:
```
yarn build
```
(Optional) Run dependency analysis:
```
yarn deps:analyze
```

Configuration

The server requires environment variables for Backstage API access:

Required Environment Variables

BACKSTAGE_BASE_URL - Base URL of your Backstage instance (e.g., https://backstage.example.com)

Authentication Configuration

Choose one of the following authentication methods:

BACKSTAGE_TOKEN - Bearer token for API access
BACKSTAGE_CLIENT_ID, BACKSTAGE_CLIENT_SECRET, BACKSTAGE_TOKEN_URL - OAuth credentials
BACKSTAGE_API_KEY - API key authentication
BACKSTAGE_SERVICE_ACCOUNT_KEY - Service account key

Example Configuration

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

Usage

Starting the Server

yarn start

The server will start and listen for MCP protocol messages on stdin/stdout.

Integration with MCP Clients

This server is designed to work with MCP-compatible clients. Configure your MCP client to use this server:

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

For global installation after NPM publishing:

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

Example Usage with LLMs

Once connected, LLMs can use natural language to interact with 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 tool

API Reference

Tool Parameters

All tools accept parameters as defined by their Zod schemas. Entity references can be provided as:

String: "component:default/user-service"
Object: { kind: "component", namespace: "default", name: "user-service" }

Response Format

All tools return JSON responses with the following structure:

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

Development

Project Structure

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

Building

yarn build

The build system uses Rollup to create optimized bundles for both CommonJS and ESM formats:

dist/index.cjs - CommonJS bundle with shebang for CLI usage
dist/index.mjs - ESM bundle
dist/index.d.ts - TypeScript declarations

Build Features

Dual Format Support: Generates both CommonJS and ESM outputs for maximum compatibility
Minification: All outputs are minified for production use with Terser
Source Maps: Includes source maps for debugging
TypeScript Declarations: Bundled .d.ts files for type safety
Global Installation: The CommonJS build includes a shebang for global npm installation
Tree Shaking: Removes unused code for smaller bundle sizes
Cross-Platform Builds: Consistent builds across Windows, macOS, and Linux
Build Validation: Automated validation with operational transparency
Error Recovery: Automatic rollback on build failures

NPM Publishing

The package is configured for publishing to NPM with:

npm publish

After publishing, the server can be installed globally:

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

Operational Transparency & Enterprise Features

This MCP server includes comprehensive operational transparency and enterprise-grade features:

Monitoring & Health Checks

Real-time Health Monitoring: Continuous system health tracking
Resource Usage Tracking: Memory, disk, and CPU monitoring
SLA Tracking: Service Level Agreement monitoring and reporting
Automated Alerts: Configurable alerting for critical conditions

Build & Dependency Management

Cross-Platform Compatibility: Consistent operation across Windows, macOS, and Linux
Dependency Analysis: Comprehensive dependency conflict detection and resolution
Build Validation: Automated build verification with rollback capabilities
Audit Trails: Complete audit logging for all operations

Error Recovery & Resilience

Network Resilience: Automatic retry logic for network operations
Build Rollback: Automatic rollback on build failures
Dependency Backup/Restore: Backup and restore capabilities for dependencies
Structured Logging: JSON-formatted logs with full context

Usage Examples

Health Monitoring

# Check system health
yarn monitor:health

# View monitoring dashboard
yarn monitor:dashboard

# Check alerts
yarn monitor:alerts

Dependency Management

# Analyze dependencies
yarn deps:analyze

# Validate dependency health
yarn deps:validate

# Cross-platform dependency operations
yarn deps:crossplatform

Build Validation

# Comprehensive build validation
yarn build:validate

# Development build
yarn build:dev

# Watch mode
yarn build:watch

Testing

yarn test

Linting

yarn lint

Adding New Tools

Create a new tool file in src/tools/
Implement the tool class with @Tool decorator
Export from src/tools/index.ts
Define Zod schema for parameters

Example:

@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 });
  }
}

Contributing

We welcome contributions! Please see our contribution guidelines and ensure all changes include appropriate tests.

Fork the repository
Create a feature branch
Make your changes with comprehensive testing
Run the full validation suite: yarn build:validate && yarn deps:analyze
Submit a pull request

License

This project is licensed under the GPLv3 License - see the file for details.

Support & Documentation

Related Projects

Backstage - The platform this server integrates with
Model Context Protocol - The protocol specification
Backstage Catalog Client - Official Backstage client library

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);