feat: implement tool metadata handling and validation, refactor related components

Author: Coderrob

.eslintignore

@@ -0,0 +1,4 @@
+dist
+.yarn
+node_modules
+coverage

package.json

@@ -1,4 +1,5 @@
 {
+  "author": "Robert Lindley",
   "dependencies": {
     "@backstage/catalog-client": "^1.9.1",
     "@backstage/catalog-model": "^1.7.3",
@@ -32,8 +33,8 @@
   "packageManager": "[email protected]",
   "scripts": {
     "build": "tsc",
-    "lint": "eslint . --ext .ts",
-    "lint:fix": "prettier . --write",
+    "lint": "eslint 'src/**/*.ts' --ext .ts",
+    "lint:fix": "prettier . --write && eslint 'src/**/*.ts' --ext .ts --fix",
     "start": "node dist/index.js",
     "test": "jest --coverage"
   },

src/api/backstage-catalog-api.ts

@@ -18,13 +18,13 @@ import {
 import { CompoundEntityRef, Entity, stringifyEntityRef } from '@backstage/catalog-model';
 import axios, { AxiosInstance, isAxiosError } from 'axios';
 
-import { AuthManager } from '../auth/auth-manager';
 import { type AuthConfig } from '../auth';
-import { CacheManager } from '../cache/cache-manager';
+import { AuthManager } from '../auth/auth-manager';
 import { securityAuditor, SecurityEventType } from '../auth/security-auditor';
-import { JsonApiDocument, JsonApiFormatter } from '../utils/jsonapi-formatter';
+import { CacheManager } from '../cache/cache-manager';
 import { logger } from '../utils';
 import { isString } from '../utils/guards';
+import { JsonApiDocument, JsonApiFormatter } from '../utils/jsonapi-formatter';
 import { PaginationHelper, PaginationParams } from '../utils/pagination-helper';
 
 interface BackstageCatalogApiOptions {

src/decorators/tool.decorator.ts

@@ -1,20 +1,14 @@
 import 'reflect-metadata';
 
-import { ToolMetadata } from '../types';
+import { IToolMetadata, ToolClass } from '../types';
 
-/**
- * Tool class constructor type. We only need to store the constructor as the key
- * in the metadata map.
- */
-export type ToolClass = new (...args: unknown[]) => unknown;
-
-const toolMetadataMap = new Map<ToolClass, ToolMetadata>();
+const toolMetadataMap = new Map<ToolClass, IToolMetadata>();
 
 export { toolMetadataMap };
 
 export const TOOL_METADATA_KEY = Symbol('TOOL_METADATA');
 
-export function Tool(metadata: ToolMetadata): ClassDecorator {
+export function Tool(metadata: IToolMetadata): ClassDecorator {
   return (target) => {
     toolMetadataMap.set(target as unknown as ToolClass, metadata);
   };

src/server.ts

@@ -5,12 +5,12 @@ import { join } from 'path';
 import { BackstageCatalogApi } from './api/backstage-catalog-api';
 import { type AuthConfig } from './auth/auth-manager';
 import { IToolRegistrationContext } from './types';
+import { logger } from './utils';
 import { DefaultToolFactory } from './utils/tool-factory';
 import { ToolLoader } from './utils/tool-loader';
 import { ReflectToolMetadataProvider } from './utils/tool-metadata';
 import { DefaultToolRegistrar } from './utils/tool-registrar';
 import { DefaultToolValidator } from './utils/tool-validator';
-import { logger } from './utils';
 
 export async function startServer(): Promise<void> {
   logger.info('Starting Backstage MCP Server');

src/tools/get_entities.tool.ts

@@ -6,9 +6,8 @@ import { BackstageCatalogApi } from '../api/backstage-catalog-api';
 import { inputSanitizer } from '../auth/input-sanitizer';
 import { Tool } from '../decorators/tool.decorator';
 import { ApiStatus, IToolRegistrationContext } from '../types';
+import { logger, ToolErrorHandler } from '../utils';
 import { formatEntityList, FormattedTextResponse, JsonToTextResponse } from '../utils/responses';
-import { ToolErrorHandler } from '../utils';
-import { logger } from '../utils';
 
 const entityFilterSchema = z.object({
   key: z.string(),

src/tools/get_entity_by_ref.tool.ts

@@ -6,7 +6,6 @@ import { inputSanitizer } from '../auth/input-sanitizer';
 import { Tool } from '../decorators/tool.decorator';
 import { ApiStatus, IToolRegistrationContext } from '../types';
 import { formatEntity, FormattedTextResponse, ToolErrorHandler } from '../utils';
-import { logger } from '../utils';
 
 const compoundEntityRefSchema = z.object({
   kind: z.string(),

src/tools/get_location_by_ref.tool.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 
 import { Tool } from '../decorators/tool.decorator';
 import { ApiStatus, IToolRegistrationContext } from '../types';
-import { formatLocation, FormattedTextResponse, JsonToTextResponse } from '../utils/responses';
+import { formatLocation, FormattedTextResponse } from '../utils/responses';
 import { ToolErrorHandler } from '../utils/tool-error-handler';
 
 const paramsSchema = z.object({

src/types.ts

@@ -1,9 +1,18 @@
 /* eslint-disable import/no-unused-modules */
 import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { z } from 'zod';
 
 import { BackstageCatalogApi } from './api/backstage-catalog-api';
+export type { IToolMetadata, RawToolMetadata } from './types/tool-metadata';
+import type { IToolMetadata } from './types/tool-metadata';
+
+export interface ILogger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  fatal(message: string, ...args: unknown[]): void;
+}
 
 export enum ApiStatus {
   SUCCESS = 'success',
@@ -25,34 +34,30 @@ export interface IToolRegistrationContext {
 
 export type ToolRegistration = (context: IToolRegistrationContext) => RegisteredTool;
 
-export interface ToolMetadata {
-  name: string;
-  description: string;
-  paramsSchema: z.ZodTypeAny;
-}
+// IToolMetadata is exported from src/types/tool-metadata.ts
 
-export interface Tool {
+export interface ITool {
   execute(args: unknown, context: object): Promise<CallToolResult>;
 }
 
-export interface ToolMetadataProvider {
-  getMetadata(toolClass: unknown): ToolMetadata | undefined;
+export interface IToolMetadataProvider {
+  getMetadata(toolClass: ToolClass): IToolMetadata | undefined;
 }
 
-export interface ToolValidator {
-  validate(metadata: ToolMetadata, file: string): void;
+export interface IToolValidator {
+  validate(metadata: IToolMetadata, file: string): void;
 }
 
-export interface ToolRegistrar {
-  register(toolClass: ToolConstructor, metadata: ToolMetadata): void;
+export interface IToolRegistrar {
+  register(toolClass: ToolClass, metadata: IToolMetadata): void;
 }
 
-export interface ToolFactory {
-  loadTool(filePath: string): Promise<ToolConstructor | undefined>;
+export interface IToolFactory {
+  loadTool(filePath: string): Promise<IToolConstructor | undefined>;
 }
 
-export type ToolConstructor = {
+export interface IToolConstructor {
   execute(args: unknown, context: object): Promise<CallToolResult>;
-};
+}
 
-export type ToolClass = ToolConstructor | undefined;
+export type ToolClass = unknown;

src/types/tool-metadata.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+/**
+ * RawToolMetadata represents metadata as it appears in a file/manifest
+ * (paramsSchema is a plain object shape when authored in JSON/JS).
+ */
+export const rawToolMetadataSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().min(1),
+  paramsSchema: z.record(z.any()).optional(),
+});
+
+export type RawToolMetadata = z.infer<typeof rawToolMetadataSchema>;
+
+/**
+ * IToolMetadata is the runtime form used by the registrar/factory: paramsSchema
+ * is a Zod schema (z.ZodTypeAny).
+ */
+export interface IToolMetadata {
+  name: string;
+  description: string;
+  paramsSchema?: z.ZodTypeAny;
+}