MCP OpenAPI Server

Instructions

Implementation Reference

• src/McpService.ts:218-247 (registration)

  Registration of the 'load-api-schema-by-schemaName' MCP tool, including input schema (specId and schemaName using Zod) and the inline handler function that delegates to specExplorer.findSchemaByName and returns the schema as YAML string.

  server.tool(
    "load-api-schema-by-schemaName",
    "Load a schema by schemaName",
    {
      specId: z.string(),
      schemaName: z.string(),
    },
    async (args, extra) => {
      try {
        this.logger.debug('Loading API schema', { specId: args.specId, schemaName: args.schemaName });
        const schema = await this.specExplorer.findSchemaByName(
          args.specId,
          args.schemaName
        );
        if (!schema) {
          this.logger.warn('Schema not found', { specId: args.specId, schemaName: args.schemaName });
        }
        return {
          content: [{ type: "text", text: stringify(schema, { indent: 2 }) }],
        };
      } catch (error) {
        this.logger.error('Failed to load API schema', {
          error,
          specId: args.specId,
          schemaName: args.schemaName
        });
        throw error;
      }
    }
  );

• src/McpService.ts:221-224 (schema)

  Zod input schema for the tool parameters: specId (string) and schemaName (string).

  {
    specId: z.string(),
    schemaName: z.string(),
  },

• src/core/SpecService.ts:417-437 (helper)

  Core implementation of schema lookup by name in FileSystemSpecService: retrieves the OpenAPI spec from cache, extracts the schema from components.schemas[schemaName], and returns a structured LoadSchemaResult.

  async findSchemaByName(
    specId: string,
    schemaName: string
  ): Promise<LoadSchemaResult | null> {
    const spec = this.specs[specId];
    if (!spec) {
      return null;
    }
    const schema = spec.components?.schemas?.[schemaName];
    if (!schema) {
      return null;
    }
  
    // all references must have been dereferenced
    return {
      name: schemaName,
      description: schema["description"],
      schema: schema as OpenAPIV3.SchemaObject,
      uri: `apis://${specId}/schemas/${schemaName}`,
    };
  }