initial wip on tool creation and registration

Author: Coderrob

.editorconfig

@@ -0,0 +1,8 @@
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+max_line_length = 80
+trim_trailing_whitespace = true

.prettierrc

@@ -0,0 +1,4 @@
+trailingComma: 'es5'
+tabWidth: 2
+semi: true
+singleQuote: true

README.md

@@ -1 +1 @@
-# backstage-mcp-server
+# backstage-mcp-server

package.json

@@ -0,0 +1,30 @@
+{
+  "dependencies": {
+    "@backstage/catalog-client": "^1.9.1",
+    "@backstage/catalog-model": "^1.7.3",
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "axios": "^1.9.0",
+    "reflect-metadata": "^0.2.2",
+    "yarn": "^1.22.22",
+    "zod": "^3.22.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.4",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.3",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "main": "dist/server.js",
+  "name": "mcp-backstage-server",
+  "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e",
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "npx prettier . --write",
+    "start": "node dist/server.js",
+    "test": "jest --coverage"
+  },
+  "version": "1.0.0"
+}

src/api/backstage-catalog-api.ts

@@ -0,0 +1,214 @@
+import axios, { AxiosInstance } from 'axios';
+import {
+  AddLocationRequest,
+  AddLocationResponse,
+  CatalogApi,
+  CatalogRequestOptions,
+  GetEntitiesByRefsRequest,
+  GetEntitiesByRefsResponse,
+  GetEntitiesRequest,
+  GetEntitiesResponse,
+  GetEntityAncestorsRequest,
+  GetEntityAncestorsResponse,
+  GetEntityFacetsRequest,
+  GetEntityFacetsResponse,
+  Location,
+  QueryEntitiesRequest,
+  QueryEntitiesResponse,
+  ValidateEntityResponse,
+} from '@backstage/catalog-client';
+import {
+  CompoundEntityRef,
+  Entity,
+  stringifyEntityRef,
+} from '@backstage/catalog-model';
+import { isString } from '../utils/guards';
+
+interface BackstageCatalogApiOptions {
+  baseUrl: string;
+  token?: string;
+}
+
+export class BackstageCatalogApi implements CatalogApi {
+  private readonly client: AxiosInstance;
+
+  constructor({ baseUrl, token }: BackstageCatalogApiOptions) {
+    this.client = axios.create({
+      baseURL: `${baseUrl.replace(/\/$/, '')}/v1`,
+      headers: token ? { Authorization: `Bearer ${token}` } : {},
+    });
+  }
+
+  async getEntities(
+    request?: GetEntitiesRequest,
+    _options?: CatalogRequestOptions
+  ): Promise<GetEntitiesResponse> {
+    const { data } = await this.client.get<GetEntitiesResponse>('/entities', {
+      params: request,
+    });
+    return data;
+  }
+
+  async getEntitiesByRefs(
+    request: GetEntitiesByRefsRequest,
+    _options?: CatalogRequestOptions
+  ): Promise<GetEntitiesByRefsResponse> {
+    const { entityRefs } = request;
+    const { data } = await this.client.post<GetEntitiesByRefsResponse>(
+      '/entities/by-refs',
+      { entityRefs }
+    );
+    return data;
+  }
+
+  async queryEntities(
+    request?: QueryEntitiesRequest,
+    _options?: CatalogRequestOptions
+  ): Promise<QueryEntitiesResponse> {
+    const { data } = await this.client.post<QueryEntitiesResponse>(
+      '/entities/query',
+      request
+    );
+    return data;
+  }
+
+  async getEntityAncestors(
+    request: GetEntityAncestorsRequest,
+    _options?: CatalogRequestOptions
+  ): Promise<GetEntityAncestorsResponse> {
+    const { entityRef } = request;
+    const { data } = await this.client.get<GetEntityAncestorsResponse>(
+      `/entities/by-ref/${encodeURIComponent(entityRef)}/ancestry`
+    );
+    return data;
+  }
+
+  async getEntityByRef(
+    entityRef: string | CompoundEntityRef,
+    _options?: CatalogRequestOptions
+  ): Promise<Entity | undefined> {
+    const refString = isString(entityRef)
+      ? entityRef
+      : this.formatCompoundEntityRef(entityRef);
+    try {
+      const { data } = await this.client.get<Entity>(
+        `/entities/by-ref/${encodeURIComponent(refString)}`
+      );
+      return data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.status === 404)
+        return undefined;
+      throw error;
+    }
+  }
+
+  async removeEntityByUid(
+    uid: string,
+    _options?: CatalogRequestOptions
+  ): Promise<void> {
+    await this.client.delete(`/entities/by-uid/${encodeURIComponent(uid)}`);
+  }
+
+  async refreshEntity(
+    entityRef: string,
+    _options?: CatalogRequestOptions
+  ): Promise<void> {
+    await this.client.post(`/refresh`, { entityRef });
+  }
+
+  async getEntityFacets(
+    request: GetEntityFacetsRequest,
+    _options?: CatalogRequestOptions
+  ): Promise<GetEntityFacetsResponse> {
+    const { data } = await this.client.post<GetEntityFacetsResponse>(
+      '/entities/facets',
+      request
+    );
+    return data;
+  }
+
+  async getLocationById(
+    id: string,
+    _options?: CatalogRequestOptions
+  ): Promise<Location | undefined> {
+    try {
+      const { data } = await this.client.get<Location>(
+        `/locations/${encodeURIComponent(id)}`
+      );
+      return data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.status === 404)
+        return undefined;
+      throw error;
+    }
+  }
+
+  async getLocationByRef(
+    locationRef: string,
+    _options?: CatalogRequestOptions
+  ): Promise<Location | undefined> {
+    try {
+      const { data } = await this.client.get<Location>(
+        `/locations/by-ref/${encodeURIComponent(locationRef)}`
+      );
+      return data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.status === 404)
+        return undefined;
+      throw error;
+    }
+  }
+
+  async addLocation(
+    location: AddLocationRequest,
+    _options?: CatalogRequestOptions
+  ): Promise<AddLocationResponse> {
+    const { data } = await this.client.post<AddLocationResponse>(
+      '/locations',
+      location
+    );
+    return data;
+  }
+
+  async removeLocationById(
+    id: string,
+    _options?: CatalogRequestOptions
+  ): Promise<void> {
+    await this.client.delete(`/locations/${encodeURIComponent(id)}`);
+  }
+
+  async getLocationByEntity(
+    entityRef: string | CompoundEntityRef,
+    _options?: CatalogRequestOptions
+  ): Promise<Location | undefined> {
+    const refString = isString(entityRef)
+      ? entityRef
+      : this.formatCompoundEntityRef(entityRef);
+    try {
+      const { data } = await this.client.get<Location>(
+        `/locations/by-entity/${encodeURIComponent(refString)}`
+      );
+      return data;
+    } catch (error) {
+      if (axios.isAxiosError(error) && error.response?.status === 404)
+        return undefined;
+      throw error;
+    }
+  }
+
+  async validateEntity(
+    entity: Entity,
+    locationRef: string,
+    _options?: CatalogRequestOptions
+  ): Promise<ValidateEntityResponse> {
+    const { data } = await this.client.post<ValidateEntityResponse>(
+      '/validate-entity',
+      { entity, locationRef }
+    );
+    return data;
+  }
+
+  private formatCompoundEntityRef(entityRef: CompoundEntityRef): string {
+    return stringifyEntityRef(entityRef);
+  }
+}

src/decorators/index.ts

@@ -0,0 +1 @@
+export { TOOL_METADATA_KEY, Tool } from './tool.decorator';

src/decorators/tool.decorator.ts

@@ -0,0 +1,9 @@
+import 'reflect-metadata';
+import { ToolMetadata } from '../types';
+
+export const TOOL_METADATA_KEY = Symbol('TOOL_METADATA');
+
+export function Tool(metadata: ToolMetadata): ClassDecorator {
+  return (target) =>
+    Reflect.defineMetadata(TOOL_METADATA_KEY, metadata, target);
+}

src/index.ts

@@ -0,0 +1,8 @@
+import { startServer } from './server';
+
+(async function () {
+  await startServer().catch((err) => {
+    console.error('Fatal server startup error:', err);
+    process.exit(1);
+  });
+})();

src/server.ts

@@ -0,0 +1,27 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { BackstageCatalogApi } from './api/backstage-catalog-api';
+import { IToolRegistrationContext } from './types';
+import { ToolLoader } from './utils/tool-loader';
+
+export async function startServer(): Promise<void> {
+  const server = new McpServer({
+    name: 'Backstage MCP Server',
+    version: '1.0.0',
+  });
+
+  const context: IToolRegistrationContext = {
+    server,
+    catalogClient: new BackstageCatalogApi({ baseUrl: '' }),
+  };
+
+  const toolLoader = new ToolLoader('./tools', context);
+  await toolLoader.registerAllTools();
+
+  if (process.env.NODE_ENV !== 'production') {
+    await toolLoader.exportManifest('./tools-manifest.json');
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

src/tools/add_location.tool.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+import { ApiStatus, IToolRegistrationContext } from '../types';
+import { JsonToTextResponse } from '../utils/responses';
+import { Tool } from '../decorators/tool.decorator';
+import { AddLocationRequest } from '@backstage/catalog-client';
+
+const paramsSchema = z.custom<AddLocationRequest>();
+
+@Tool({
+  name: 'add_location',
+  description: 'Create a new location in the catalog.',
+  paramsSchema: paramsSchema,
+})
+export class AddLocationTool {
+  static async execute(
+    request: z.infer<typeof paramsSchema>,
+    context: IToolRegistrationContext
+  ) {
+    const result = await context.catalogClient.addLocation(request);
+    return JsonToTextResponse({ status: ApiStatus.SUCCESS, data: result });
+  }
+}