mcp-openapi-schema-explorer 1.0.0

package/memory-bank/activeContext.md

@@ -0,0 +1,139 @@
+# Active Context
+
+## Current Focus
+
+Completed setup of automated versioning and releases using `semantic-release` and updated the CI workflow. Corrected dependency categorization in `package.json`. Updated Memory Bank.
+
+## Recent Progress
+
+### Dependency Cleanup & Release Automation (✓)
+
+1.  **Dependency Correction:**
+    - Moved `swagger2openapi` from `devDependencies` to `dependencies` in `package.json`.
+    - Moved `@types/js-yaml` from `dependencies` to `devDependencies` in `package.json`.
+    - Removed unused `@types/swagger-parser` from `devDependencies` in `package.json`.
+    - Ran `npm install` to update `package-lock.json`.
+2.  **Semantic Release Setup:**
+    - Installed `semantic-release` and plugins (`@semantic-release/commit-analyzer`, `@semantic-release/release-notes-generator`, `@semantic-release/changelog`, `@semantic-release/npm`, `@semantic-release/github`, `@semantic-release/git`, `@semantic-release/exec`) as dev dependencies.
+    - Created `scripts/generate-version.js` to write the release version to `src/version.ts`.
+    - Created `.releaserc.json` configuring the release workflow, including using `@semantic-release/exec` to run the generation script and `@semantic-release/git` to commit `src/version.ts`.
+    - Updated `eslint.config.js` to correctly lint the `generate-version.js` script.
+3.  **Dynamic Versioning:**
+    - Created a default `src/version.ts` file (with version `0.0.0-dev`) tracked by Git to ensure local/CI builds work.
+    - Updated `src/index.ts` to import `VERSION` from `src/version.ts` and use it in the `McpServer` constructor.
+    - The default `src/version.ts` will be overwritten with the correct release version by `semantic-release` during the release process.
+4.  **CI Workflow Adaptation:**
+    - Updated `.github/workflows/ci.yml`.
+    - Removed Docker Compose dependency from the `test` job.
+    - Standardized on Node 22 for `test` and `security` jobs.
+    - Added `extractions/setup-just@v3` action to both jobs.
+    - Updated `test` job to run checks via `just all`.
+    - Updated `security` job to run checks via `just security` (keeping CodeQL separate).
+    - Added a new `release` job triggered on pushes to `main` (after `test` and `security` pass) that runs `npx semantic-release`. Configured necessary permissions and environment variables (`GITHUB_TOKEN`, placeholder for `NPM_TOKEN`).
+5.  **Memory Bank Update (✓):** Updated `activeContext.md`, `progress.md`, `systemPatterns.md`, and `techContext.md`.
+
+### Dynamic Server Name (✓)
+
+1.  **Spec Loading:** Modified `src/index.ts` to load the OpenAPI spec using `createSpecLoader` _before_ initializing `McpServer`.
+2.  **Name Generation:** Extracted `info.title` from the loaded spec and constructed a dynamic server name (`Schema Explorer for {title}`) with a fallback to `'OpenAPI Schema Explorer'`.
+3.  **Server Initialization:** Updated `McpServer` constructor in `src/index.ts` to use the generated dynamic name.
+4.  **Dependency Injection:** Confirmed handlers already receive the shared `specLoader` instance correctly, requiring no changes to handler constructors.
+5.  **Memory Bank Update (✓):** Updated `activeContext.md` and `progress.md`.
+
+### Resource Completion Logic (✓)
+
+1.  **Implementation:** Modified `src/index.ts` to define `ResourceTemplate` objects directly within `server.resource()` calls. Added `complete` property with functions providing suggestions for `{field}`, `{path}`, `{method*}`, and `{type}` based on the loaded `transformedSpec`.
+2.  **Conditional Name Completion:** Implemented logic for the `{name*}` completion in the `openapi://components/{type}/{name*}` template. It now provides component names only if the spec contains exactly one component type (e.g., only `schemas`). Otherwise, it returns an empty list. Used `getValidatedComponentMap` helper for safe access.
+3.  **Testing:**
+    - Added new E2E test suite (`Completion Tests`) to `test/__tests__/e2e/resources.test.ts` using the `client.complete()` method.
+    - Added new test fixture `test/fixtures/multi-component-types.json` to cover the multi-type scenario for name completion.
+    - Verified all tests pass.
+4.  **Memory Bank Update (✓):** Updated `activeContext.md`, `progress.md`, `systemPatterns.md`, and `projectbrief.md`.
+
+### Dynamic Server Name (✓)
+
+1.  **Spec Loading:** Modified `src/index.ts` to load the OpenAPI spec using `createSpecLoader` _before_ initializing `McpServer`.
+2.  **Name Generation:** Extracted `info.title` from the loaded spec and constructed a dynamic server name (`Schema Explorer for {title}`) with a fallback to `'OpenAPI Schema Explorer'`.
+3.  **Server Initialization:** Updated `McpServer` constructor in `src/index.ts` to use the generated dynamic name.
+4.  **Dependency Injection:** Confirmed handlers already receive the shared `specLoader` instance correctly, requiring no changes to handler constructors.
+5.  **Memory Bank Update (✓):** Updated `activeContext.md` and `progress.md`.
+
+### Minified JSON Output Format (✓)
+
+1.  **Formatter:** Added `MinifiedJsonFormatter` to `src/services/formatters.ts` and updated `OutputFormat` type and `createFormatter` function.
+2.  **Configuration:** Updated `src/config.ts` to accept `--output-format json-minified`.
+3.  **Unit Tests:** Added unit tests for `MinifiedJsonFormatter` in `test/__tests__/unit/services/formatters.test.ts`.
+4.  **E2E Tests:** Added E2E tests for the `json-minified` format in `test/__tests__/e2e/format.test.ts`.
+5.  **Test Helpers:** Updated `StartServerOptions` type in `test/utils/mcp-test-helpers.ts`.
+6.  **Memory Bank Update (✓):** Updated `techContext.md`, `systemPatterns.md`, `progress.md`, and `activeContext.md`.
+
+### Remote Spec & Swagger v2.0 Support (✓)
+
+1.  **Remote Loading:** Added support for loading specifications via HTTP/HTTPS URLs using `swagger2openapi` in `SpecLoaderService`.
+2.  **Swagger v2.0 Conversion:** Added support for automatically converting Swagger v2.0 specifications to OpenAPI v3.0 using `swagger2openapi` in `SpecLoaderService`.
+3.  **Dependency Change:** Replaced `@apidevtools/swagger-parser` with `swagger2openapi`. Added `@types/swagger2openapi`. Reinstalled `openapi-types`.
+4.  **Configuration:** Confirmed configuration uses CLI arguments (`<path-or-url-to-spec>`).
+5.  **Testing:**
+    - Updated `SpecLoaderService` unit tests (`spec-loader.test.ts`) to mock `swagger2openapi` and cover new scenarios (local/remote, v2/v3). Fixed linting/hoisting issues in mocks.
+    - Created new E2E test file (`spec-loading.test.ts`) to verify loading from local v2 and remote v3 sources. Added necessary helpers and fixed linting issues.
+    - Added v2.0 test fixture (`sample-v2-api.json`).
+6.  **Memory Bank Update (✓):** Updated `productContext.md`, `techContext.md`, `systemPatterns.md`, `progress.md`, and `activeContext.md` to reflect these changes.
+
+### Major Refactor (Previously Completed - ✓)
+
+1.  **Unified URI Structure:** Implemented consistent URIs based on OpenAPI spec hierarchy (`openapi://{field}`, `openapi://paths/...`, `openapi://components/...`).
+2.  **OOP Rendering Layer:** Created `Renderable*` classes for modular rendering logic (`src/rendering/`).
+3.  **Refactored Handlers:** Replaced old handlers with new, focused handlers (`src/handlers/`).
+    - `TopLevelFieldHandler`
+    - `PathItemHandler`
+    - `OperationHandler`
+    - `ComponentMapHandler`
+    - `ComponentDetailHandler`
+4.  **Shared Utilities:** Extracted common logic into `src/rendering/utils.ts` and `src/handlers/handler-utils.ts`.
+5.  **Multi-Value Handling:** Correctly implemented handling for `*` variables (`method*`, `name*`).
+6.  **Testing:**
+    - Added/passed unit tests for all `Renderable*` classes.
+    - Added/passed E2E tests for the new URI structure using `complex-endpoint.json`.
+7.  **Documentation:** Updated `systemPatterns.md` and `progress.md`.
+8.  **Archived Old Code:** Moved previous implementations to `local-docs/old-implementation/`.
+9.  **URI Generation Refactor (✓):**
+    - Created centralized URI builder utility (`src/utils/uri-builder.ts`).
+    - Updated `$ref` transformation (`src/services/reference-transform.ts`) to use the builder and support all component types (`openapi://components/{type}/{name}`).
+    - Updated hint generation (`src/rendering/utils.ts`, `components.ts`, `path-item.ts`) to use the builder.
+    - Corrected path encoding in builder (removed leading slash encoding).
+    - Updated relevant unit tests (`uri-builder.test.ts`, `reference-transform.test.ts`, `path-item.test.ts`).
+    - Fixed `RenderablePathItem` instantiation in handlers (`path-item-handler.ts`, `operation-handler.ts`).
+10. **Security Fix (✓):** Resolved `security/detect-object-injection` warnings by implementing Map-based validation helpers (`getValidatedPathItem`, `getValidatedOperations`, `getValidatedComponentMap`, `getValidatedComponentDetails`) in `handler-utils.ts` and refactoring handlers (`operation-handler`, `path-item-handler`, `component-map-handler`, `component-detail-handler`) and rendering classes (`RenderablePaths`, `RenderableComponents`, `RenderableComponentMap`) to use safe access patterns inspired by the old implementation.
+
+## Implementation Status
+
+- Server now loads OpenAPI v3.0 and Swagger v2.0 specs from local files or remote URLs.
+- Swagger v2.0 specs are automatically converted to v3.0.
+- Internal references are transformed to MCP URIs.
+- Added `json-minified` output format option.
+- Server name is now dynamically set based on the loaded spec's `info.title`.
+- **New:** Automated versioning and release process implemented using `semantic-release`.
+- **New:** CI workflow adapted for Node 22, uses `just` for checks, and includes a release job.
+- Dependencies correctly categorized (`swagger2openapi` in `dependencies`, types in `devDependencies`).
+- Resource completion logic implemented.
+- Dynamic server name implemented.
+- Minified JSON output format added.
+- Remote spec loading and Swagger v2.0 conversion support added.
+- Core resource exploration functionality remains operational.
+- Unit tests for `SpecLoaderService` and `Formatters` are updated.
+- E2E tests cover basic loading scenarios, output formats, resource exploration, and resource completion.
+
+## Next Actions / Immediate Focus
+
+1.  **README Update:** Enhance `README.md` with:
+    - Details about the automated release process and the requirement for Conventional Commits.
+    - Instructions for setting up the `NPM_TOKEN` secret for publishing.
+    - Updated usage examples and explanations (including `json-minified` format).
+2.  **Handler Unit Tests:** Implement comprehensive unit tests for each handler class (`TopLevelFieldHandler`, `PathItemHandler`, etc.), mocking `SpecLoaderService` and `IFormatter`.
+3.  **Refactor Helpers:** Consolidate duplicated helper functions (`formatResults`, `isOpenAPIV3`) fully into `handler-utils.ts` and remove from individual handlers.
+4.  **Code Cleanup:** Address remaining TODOs (e.g., checking warnings in `spec-loader.ts`) and minor ESLint warnings.
+
+## Future Considerations (Post Immediate Actions)
+
+- Implement reference traversal/resolution service.
+- Enhance support for all component types.

package/memory-bank/productContext.md

@@ -0,0 +1,39 @@
+# Product Context
+
+## Problem Statement
+
+When working with large OpenAPI specifications, loading the entire spec into an LLM's context:
+
+1. Consumes excessive tokens due to fully resolved references
+2. May confuse the LLM with too much information
+3. Makes it difficult to focus on specific parts of the API
+4. Duplicates schema information across multiple endpoints
+
+## Solution
+
+An MCP server that:
+
+1. Loads OpenAPI v3.0 and Swagger v2.0 specs from local files or remote URLs.
+2. Automatically converts Swagger v2.0 specs to OpenAPI v3.0.
+3. Transforms internal references (`#/components/...`) to token-efficient MCP URIs.
+4. Provides selective access to specific parts of the spec via MCP resources.
+5. Returns information in token-efficient formats (text lists, JSON/YAML details).
+6. Makes it easy for LLMs to explore API structures without loading the entire spec.
+
+## User Experience Goals
+
+1. Easy installation via npm.
+2. Simple configuration via a single command-line argument (path or URL).
+3. Intuitive resource URIs for exploring API parts.
+4. Clear and consistent response formats.
+
+## Usage Workflow
+
+1. User installs MCP server via `npm install -g mcp-openapi-schema-explorer`.
+2. User runs the server providing the path or URL to the spec file via CLI argument (e.g., `mcp-openapi-schema-explorer ./spec.yaml` or `mcp-openapi-schema-explorer https://.../spec.json`).
+3. Server loads the spec (from file or URL), converts v2.0 to v3.0 if necessary, and transforms internal references to MCP URIs.
+4. LLM explores API structure through exposed resources:
+   - List paths, components, methods.
+   - View details for info, operations, components, etc.
+   - Follow transformed reference URIs (`openapi://components/...`) to view component details without loading the whole spec initially.
+5. Server restarts required if the source specification file/URL content changes.

package/memory-bank/progress.md

@@ -0,0 +1,141 @@
+# Project Progress
+
+## Completed Features
+
+### Core Refactoring & New Resource Structure (✓)
+
+1.  **Unified URI Structure:** Implemented a consistent URI structure based on OpenAPI spec hierarchy:
+    - `openapi://{field}`: Access top-level fields (info, servers, tags) or list paths/component types.
+    - `openapi://paths/{path}`: List methods for a specific path.
+    - `openapi://paths/{path}/{method*}`: Get details for one or more operations.
+    - `openapi://components/{type}`: List names for a specific component type.
+    - `openapi://components/{type}/{name*}`: Get details for one or more components.
+2.  **OOP Rendering Layer:** Introduced `Renderable*` classes (`RenderableDocument`, `RenderablePaths`, `RenderablePathItem`, `RenderableComponents`, `RenderableComponentMap`) to encapsulate rendering logic.
+    - Uses `RenderContext` and intermediate `RenderResultItem` structure.
+    - Supports token-efficient text lists and formatted detail views (JSON/YAML).
+3.  **Refactored Handlers:** Created new, focused handlers for each URI pattern:
+    - `TopLevelFieldHandler`
+    - `PathItemHandler`
+    - `OperationHandler`
+    - `ComponentMapHandler`
+    - `ComponentDetailHandler`
+    - Uses shared utilities (`handler-utils.ts`).
+4.  **Multi-Value Support:** Correctly handles `*` variables (`method*`, `name*`) passed as arrays by the SDK.
+5.  **Testing:**
+    - Added unit tests for all new `Renderable*` classes.
+    - Added unit tests for all new handler classes.
+    - Added E2E tests covering the new URI structure and functionality using `complex-endpoint.json`.
+6.  **Archived Old Code:** Moved previous handler/test implementations to `local-docs/old-implementation/`.
+
+### Previous Features (Now Integrated/Superseded)
+
+- Schema Listing (Superseded by `openapi://components/schemas`)
+- Schema Details (Superseded by `openapi://components/schemas/{name*}`)
+- Endpoint Details (Superseded by `openapi://paths/{path}/{method*}`)
+- Endpoint List (Superseded by `openapi://paths`)
+
+### Remote Spec & Swagger v2.0 Support (✓)
+
+1.  **Remote Loading:** Added support for loading specifications via HTTP/HTTPS URLs using `swagger2openapi`.
+2.  **Swagger v2.0 Conversion:** Added support for automatically converting Swagger v2.0 specifications to OpenAPI v3.0 using `swagger2openapi`.
+3.  **Dependency Change:** Replaced `@apidevtools/swagger-parser` with `swagger2openapi` for loading and conversion.
+4.  **Configuration Update:** Confirmed and documented that configuration uses CLI arguments (`<path-or-url-to-spec>`) instead of environment variables.
+5.  **Testing:**
+    - Updated `SpecLoaderService` unit tests to mock `swagger2openapi` and cover new scenarios (local/remote, v2/v3).
+    - Created new E2E test file (`spec-loading.test.ts`) to verify loading from local v2 and remote v3 sources.
+    - Added v2.0 test fixture (`sample-v2-api.json`).
+
+## Technical Features (✓)
+
+### Codebase Organization (Updated)
+
+1. File Structure
+
+   - `src/handlers/`: Contains individual handlers and `handler-utils.ts`.
+   - `src/rendering/`: Contains `Renderable*` classes, `types.ts`, `utils.ts`.
+   - `src/services/`: Updated `spec-loader.ts` to use `swagger2openapi`. Added `formatters.ts`.
+   - `src/`: `index.ts`, `config.ts`, `types.ts`.
+   - `test/`: Updated unit tests (`spec-loader.test.ts`, `formatters.test.ts`), added new E2E test (`spec-loading.test.ts`), added v2 fixture. Updated `format.test.ts`. Updated `mcp-test-helpers.ts`.
+   - `local-docs/old-implementation/`: Archived previous code.
+
+2. Testing Structure
+
+   - Unit tests for rendering classes (`test/__tests__/unit/rendering/`).
+   - Unit tests for handlers (`test/__tests__/unit/handlers/`).
+   - Unit tests for services (`spec-loader.test.ts`, `reference-transform.test.ts`, `formatters.test.ts`).
+   - E2E tests (`refactored-resources.test.ts`, `spec-loading.test.ts`, `format.test.ts`). Added tests for `json-minified`.
+   - Fixtures (`test/fixtures/`, including v2 and v3).
+   - Test utils (`test/utils/`). Updated `StartServerOptions` type.
+
+3. Type System
+
+   - OpenAPI v3 types.
+   - `RenderableSpecObject`, `RenderContext`, `RenderResultItem` interfaces.
+   - `FormattedResultItem` type for handler results.
+   - `OutputFormat` type updated.
+   - `IFormatter` interface.
+
+4. Error Handling
+   - Consistent error handling via `createErrorResult` and `formatResults`.
+   - Errors formatted as `text/plain`.
+
+### Reference Transformation (✓ - Updated)
+
+- Centralized URI generation logic in `src/utils/uri-builder.ts`.
+- `ReferenceTransformService` now correctly transforms all `#/components/...` refs to `openapi://components/{type}/{name}` using the URI builder.
+- Path encoding corrected to remove leading slashes before encoding.
+- Unit tests updated and passing for URI builder and transformer.
+
+### Output Format Enhancement (✓)
+
+- Added `json-minified` output format option (`--output-format json-minified`).
+- Implemented `MinifiedJsonFormatter` in `src/services/formatters.ts`.
+- Updated configuration (`src/config.ts`) to accept the new format.
+- Added unit tests for the new formatter (`test/__tests__/unit/services/formatters.test.ts`).
+- Added E2E tests (`test/__tests__/e2e/format.test.ts`) to verify the new format.
+- Updated test helper types (`test/utils/mcp-test-helpers.ts`).
+
+### Dynamic Server Name (✓)
+
+- Modified `src/index.ts` to load the OpenAPI spec before server initialization.
+- Extracted `info.title` from the loaded spec.
+- Set the `McpServer` name dynamically using the format `Schema Explorer for {title}` with a fallback.
+
+### Dependency Cleanup & Release Automation (✓)
+
+1.  **Dependency Correction:** Correctly categorized runtime (`swagger2openapi`) vs. development (`@types/*`) dependencies in `package.json`. Removed unused types.
+2.  **Automated Releases:** Implemented `semantic-release` with conventional commit analysis, changelog generation, npm publishing, and GitHub releases.
+3.  **Dynamic Versioning:** Server version is now dynamically injected via `src/version.ts`, which is generated during the release process by `semantic-release` using `scripts/generate-version.js`. A default version file is tracked in Git for local builds.
+4.  **CI Workflow:** Updated `.github/workflows/ci.yml` to use Node 22, remove Docker Compose, use `just` for running checks (`just all`, `just security`), and added a `release` job to automate publishing on pushes to `main`.
+
+## Planned Features (⏳)
+
+- **Handler Unit Tests:** Complete unit tests for all new handlers (mocking services).
+- **Refactor Helpers:** Move duplicated helpers (`formatResults`, `isOpenAPIV3`) from handlers to `handler-utils.ts`. (Deferred during refactor).
+- **Security Validation (✓):** Implemented Map-based validation helpers in `handler-utils.ts` and refactored handlers/rendering classes to resolve object injection warnings.
+- **Completion Logic (✓):** Implemented `complete` callbacks in `ResourceTemplate` definitions within `src/index.ts` for `{field}`, `{path}`, `{method*}`, `{type}`, and conditionally for `{name*}`. Added E2E tests using `client.complete()`.
+- **Reference Traversal:** Service to resolve `$ref` URIs (e.g., follow `openapi://components/schemas/Task` from an endpoint detail).
+- **Enhanced Component Support:** Ensure all component types listed in `VALID_COMPONENT_TYPES` are fully handled if present in spec. (Reference transformation now supports all types).
+- **Parameter Validation:** Add validation logic if needed. (Current Map-based approach handles key validation).
+- **Further Token Optimizations:** Explore more ways to reduce token usage in list/detail views.
+
+## Technical Improvements (Ongoing)
+
+1. Code Quality
+
+   - OOP design for rendering.
+   - Clear separation of concerns (Rendering vs. Handling vs. Services).
+   - Improved type safety in rendering/handling logic.
+
+2. Testing
+
+   - Unit tests added for rendering logic.
+   - Unit tests updated for URI builder, reference transformer, and path item rendering.
+   - E2E tests updated for new structure and complex fixture. Added tests for resource completion.
+   - Unit tests for `SpecLoaderService` updated for `swagger2openapi`.
+   - CI workflow updated to use `just` and includes automated release job.
+
+3. API Design
+   - New URI structure implemented, aligned with OpenAPI spec.
+   - Consistent list/detail pattern via rendering layer.
+   - Server now accepts remote URLs and Swagger v2.0 specs via CLI argument.

package/memory-bank/projectbrief.md

@@ -0,0 +1,50 @@
+# OpenAPI Schema Explorer MCP Server
+
+## Project Overview
+
+Building an MCP server that allows exploration of OpenAPI specification files in a selective, token-efficient manner.
+
+## Core Requirements (✓)
+
+1. Allow loading and exploring OpenAPI spec files without consuming excessive LLM tokens
+   - Token-efficient plain text listings
+   - JSON format for detailed views
+   - Error handling without excessive details
+2. Expose key parts of OpenAPI specs through MCP resources
+   - Endpoint details with full operation info
+   - Multiple values support for batch operations
+   - Resource completion support (✓)
+3. Support local OpenAPI specification files
+   - OpenAPI v3.0 support
+   - Local file loading
+   - Error handling for invalid specs
+4. Provide test coverage with Jest
+   - Full unit test coverage
+   - E2E test coverage
+   - Type-safe test implementation
+
+## Future Extensions (Out of Scope)
+
+- Remote OpenAPI specs
+- Different specification formats
+- Search functionality
+
+## Technical Constraints (✓)
+
+- Built with TypeScript MCP SDK
+- Published to npm
+- Comprehensive test coverage
+- Optimized for testability and extensibility
+
+## Project Boundaries
+
+- Initial focus on local OpenAPI spec files only
+- Focus on most important parts: endpoints and type definitions
+- Real-time spec updates are out of scope (server restart required for updates)
+
+## Next Optimizations
+
+- YAML output format for improved token efficiency
+- $ref resolution using URI links
+- Parameter validation implementation
+- Enhanced documentation support

package/memory-bank/systemPatterns.md

@@ -0,0 +1,224 @@
+# System Patterns
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    CliArg[CLI Argument (Path/URL)] --> Config[src/config.ts]
+    Config --> Server[MCP Server]
+
+    CliArg --> SpecLoader[Spec Loader Service]
+    SpecLoader -- Uses --> S2OLib[swagger2openapi Lib]
+    SpecLoader --> Transform[Reference Transform Service]
+    Transform --> Handlers[Resource Handlers]
+
+    Server --> Handlers
+
+    subgraph Services
+        SpecLoader
+        Transform
+        S2OLib
+    end
+
+    subgraph Handlers
+        TopLevelFieldHandler[TopLevelField Handler (openapi://{field})]
+        PathItemHandler[PathItem Handler (openapi://paths/{path})]
+        OperationHandler[Operation Handler (openapi://paths/{path}/{method*})]
+        ComponentMapHandler[ComponentMap Handler (openapi://components/{type})]
+        ComponentDetailHandler[ComponentDetail Handler (openapi://components/{type}/{name*})]
+    end
+
+    subgraph Formatters
+        JsonFormatter[Json Formatter]
+        YamlFormatter[Yaml Formatter]
+        MinifiedJsonFormatter[Minified Json Formatter]
+    end
+
+    subgraph Rendering (OOP)
+        RenderableDocument[RenderableDocument]
+        RenderablePaths[RenderablePaths]
+        RenderablePathItem[RenderablePathItem]
+        RenderableComponents[RenderableComponents]
+        RenderableComponentMap[RenderableComponentMap]
+        RenderUtils[Rendering Utils]
+    end
+
+    Handlers --> Rendering
+    SpecLoader --> Rendering
+
+    subgraph Utils
+        UriBuilder[URI Builder (src/utils)]
+    end
+
+    UriBuilder --> Transform
+    UriBuilder --> RenderUtils
+```
+
+## Component Structure
+
+### Services Layer
+
+- **SpecLoaderService (`src/services/spec-loader.ts`):**
+  - Uses `swagger2openapi` library.
+  - Loads specification from local file path or remote URL provided via CLI argument.
+  - Handles parsing of JSON/YAML.
+  - Automatically converts Swagger v2.0 specs to OpenAPI v3.0 objects.
+  - Provides the resulting OpenAPI v3.0 document object.
+  - Handles errors during loading/conversion.
+- **ReferenceTransformService (`src/services/reference-transform.ts`):**
+  - Takes the OpenAPI v3.0 document from `SpecLoaderService`.
+  - Traverses the document and transforms internal references (e.g., `#/components/schemas/MySchema`) into MCP URIs (e.g., `openapi://components/schemas/MySchema`).
+  - Uses `UriBuilder` utility for consistent URI generation.
+  - Returns the transformed OpenAPI v3.0 document.
+- **Formatters (`src/services/formatters.ts`):**
+  - Provide implementations for different output formats (JSON, YAML, Minified JSON).
+  - Used by handlers to serialize detail view responses.
+  - `IFormatter` interface defines `format()` and `getMimeType()`.
+  - `createFormatter` function instantiates the correct formatter based on `OutputFormat` type (`json`, `yaml`, `json-minified`).
+
+### Rendering Layer (OOP)
+
+- **Renderable Classes:** Wrapper classes (`RenderableDocument`, `RenderablePaths`, `RenderablePathItem`, `RenderableComponents`, `RenderableComponentMap`) implement `RenderableSpecObject` interface.
+- **Interface:** `RenderableSpecObject` defines `renderList()` and `renderDetail()` methods returning `RenderResultItem[]`.
+- **RenderResultItem:** Intermediate structure holding data (`unknown`), `uriSuffix`, `isError?`, `errorText?`, `renderAsList?`.
+- **RenderContext:** Passed to render methods, contains `formatter` and `baseUri`.
+- **Utils:** Helper functions (`getOperationSummary`, `generateListHint`, `createErrorResult`) in `src/rendering/utils.ts`. `generateListHint` now uses centralized URI builder logic.
+
+### Handler Layer
+
+- **Structure:** Separate handlers for each distinct URI pattern/resource type.
+- **Responsibilities:**
+  - Parse URI variables provided by SDK.
+  - Load/retrieve the transformed spec via `SpecLoaderService`.
+  - Instantiate appropriate `Renderable*` classes.
+  - Invoke the correct rendering method (`renderList` or a specific detail method like `renderTopLevelFieldDetail`, `renderOperationDetail`, `renderComponentDetail`).
+  - Format the `RenderResultItem[]` using `formatResults` from `src/handlers/handler-utils.ts`.
+  - Construct the final `{ contents: ... }` response object.
+  - Instantiate `RenderablePathItem` correctly with raw path and built suffix.
+- **Handlers:**
+  - `TopLevelFieldHandler`: Handles `openapi://{field}`. Delegates list rendering for `paths`/`components` to `RenderablePaths`/`RenderableComponents`. Renders details for other fields (`info`, `servers`, etc.) via `RenderableDocument.renderTopLevelFieldDetail`.
+  - `PathItemHandler`: Handles `openapi://paths/{path}`. Uses `RenderablePathItem.renderList` to list methods. Instantiates `RenderablePathItem` with raw path and built suffix.
+  - `OperationHandler`: Handles `openapi://paths/{path}/{method*}`. Uses `RenderablePathItem.renderOperationDetail` for operation details. Handles multi-value `method` variable. Instantiates `RenderablePathItem` with raw path and built suffix.
+  - `ComponentMapHandler`: Handles `openapi://components/{type}`. Uses `RenderableComponentMap.renderList` to list component names.
+  - `ComponentDetailHandler`: Handles `openapi://components/{type}/{name*}`. Uses `RenderableComponentMap.renderComponentDetail` for component details. Handles multi-value `name` variable.
+- **Utils:** Shared functions (`formatResults`, `isOpenAPIV3`, `FormattedResultItem` type, validation helpers) in `src/handlers/handler-utils.ts`.
+
+### Utilities Layer
+
+- **URI Builder (`src/utils/uri-builder.ts`):**
+  - Centralized functions for building full URIs (`openapi://...`) and URI suffixes.
+  - Handles encoding of path components (removing leading slash first).
+  - Used by `ReferenceTransformService` and the rendering layer (`generateListHint`, `Renderable*` classes) to ensure consistency.
+
+### Configuration Layer (`src/config.ts`)
+
+- Parses command-line arguments.
+- Expects a single required argument: the path or URL to the specification file.
+- Supports an optional `--output-format` argument (`json`, `yaml`, `json-minified`).
+- Validates arguments and provides usage instructions on error.
+  - Creates the `ServerConfig` object used by the server.
+
+## Release Automation (`semantic-release`)
+
+- **Configuration:** Defined in `.releaserc.json`.
+- **Workflow:**
+  1.  `@semantic-release/commit-analyzer`: Determines release type from conventional commits.
+  2.  `@semantic-release/release-notes-generator`: Generates release notes.
+  3.  `@semantic-release/changelog`: Updates `CHANGELOG.md`.
+  4.  `@semantic-release/npm`: Updates `version` in `package.json`.
+  5.  `@semantic-release/exec`: Runs `scripts/generate-version.js` to create/update `src/version.ts` with the new version.
+  6.  `@semantic-release/git`: Commits `package.json`, `package-lock.json`, `CHANGELOG.md`, and `src/version.ts`. Creates Git tag.
+  7.  `@semantic-release/github`: Creates GitHub Release.
+- **Trigger:** Executed by the `release` job in the GitHub Actions workflow (`.github/workflows/ci.yml`) on pushes to the `main` branch.
+- **Versioning:** The server version in `src/index.ts` is dynamically imported from the generated `src/version.ts`. A default `src/version.ts` (with `0.0.0-dev`) is kept in the repository for local builds.
+
+## Resource Design Patterns
+
+### URI Structure (Revised)
+
+- Implicit List/Detail based on path depth.
+- Aligned with OpenAPI specification structure.
+- **Templates:**
+  - `openapi://{field}`: Top-level field details (info, servers) or list trigger (paths, components).
+  - `openapi://paths/{path}`: List methods for a specific path.
+  - `openapi://paths/{path}/{method*}`: Operation details (supports multiple methods).
+  - `openapi://components/{type}`: List names for a specific component type.
+  - `openapi://components/{type}/{name*}`: Component details (supports multiple names).
+- **Completions:**
+  - Defined directly in `src/index.ts` within `ResourceTemplate` definitions passed to `server.resource()`.
+  - Uses the `transformedSpec` object loaded before server initialization.
+  - Provides suggestions for `{field}`, `{path}`, `{method*}`, `{type}`.
+  - Provides suggestions for `{name*}` _only_ if the spec contains exactly one component type.
+- **Reference URIs (Corrected):**
+  - Internal `$ref`s like `#/components/schemas/MySchema` are transformed by `ReferenceTransformService` into resolvable MCP URIs: `openapi://components/schemas/MySchema`.
+  - This applies to all component types under `#/components/`.
+  - External references remain unchanged.
+
+### Response Format Patterns
+
+1. **Token-Efficient Lists:**
+   - `text/plain` format used for all list views (`openapi://paths`, `openapi://components`, `openapi://paths/{path}`, `openapi://components/{type}`).
+   - Include hints for navigating to detail views, generated via `generateListHint` using the centralized URI builder.
+   - `openapi://paths` format: `METHOD1 METHOD2 /path`
+   - `openapi://paths/{path}` format: `METHOD: Summary/OpId`
+   - `openapi://components` format: `- type`
+   - `openapi://components/{type}` format: `- name`
+2. **Detail Views:**
+   - Use configured formatter (JSON/YAML/Minified JSON via `IFormatter`).
+   - Handled by `openapi://{field}` (for non-structural fields), `openapi://paths/{path}/{method*}`, `openapi://components/{type}/{name*}`.
+3. **Error Handling:**
+   - Handlers catch errors and use `createErrorResult` utility.
+   - `formatResults` utility formats errors into `FormattedResultItem` with `isError: true`, `mimeType: 'text/plain'`, and error message in `text`.
+4. **Type Safety:**
+   - Strong typing with OpenAPI v3 types.
+   - `Renderable*` classes encapsulate type-specific logic.
+   - `isOpenAPIV3` type guard used in handlers.
+
+## Extension Points
+
+1. Reference Transformers:
+
+   - AsyncAPI transformer
+   - GraphQL transformer
+   - Custom format transformers
+
+2. Resource Handlers:
+
+   - Schema resource handler
+   - Additional reference handlers
+   - Custom format handlers (via `IFormatter` interface)
+
+3. URI Resolution:
+
+   - Reference transformation service (`ReferenceTransformService`) handles converting `#/components/{type}/{name}` to `openapi://components/{type}/{name}` URIs during spec loading.
+   - Cross-resource linking is implicit via generated URIs in hints and transformed refs.
+   - External references are currently kept as-is.
+
+4. Validation:
+   - Parameter validation
+   - Reference validation
+   - Format-specific validation
+
+## Testing Strategy
+
+1. **Unit Tests:**
+   - `SpecLoaderService`: Mock `swagger2openapi` to test local/remote and v2/v3 loading logic, including error handling.
+   - `ReferenceTransformService`: Verify correct transformation of `#/components/...` refs to MCP URIs.
+   - Rendering Classes (`Renderable*`): Test list and detail rendering logic.
+   - Handlers: Mock services (`SpecLoaderService`, `IFormatter`) to test URI parsing and delegation to rendering classes.
+   - `UriBuilder`: Test URI encoding and generation.
+2. **E2E Tests:**
+   - Use `mcp-test-helpers` to start the server with different spec inputs.
+   - **`spec-loading.test.ts`:** Verify basic resource access (`info`, `paths`, `components`, specific component detail) works correctly when loading:
+     - Local Swagger v2.0 spec (`test/fixtures/sample-v2-api.json`).
+     - Remote OpenAPI v3.0 spec (e.g., Petstore URL).
+   - **`refactored-resources.test.ts`:** Continue to test detailed resource interactions (multi-value params, specific path/method/component combinations, errors) using the primary complex local v3 fixture (`complex-endpoint.json`).
+   - **`format.test.ts`:** Verify different output formats (JSON/YAML/Minified JSON) work as expected.
+   - **Completion Tests:** Added to `refactored-resources.test.ts` using `client.complete()` to verify completion logic.
+3. **Test Support:**
+   - Type-safe test utilities (`mcp-test-helpers`). Updated `StartServerOptions` to include `json-minified`.
+   - Test fixtures for v2.0 and v3.0 specs.
+4. **CI Integration (`.github/workflows/ci.yml`):**
+   - **`test` Job:** Runs on push/PR to `main`. Uses Node 22, installs `just`, runs `npm ci`, then `just all` (format, lint, build, test). Uploads coverage.
+   - **`security` Job:** Runs on push/PR to `main`. Uses Node 22, installs `just`, runs `npm ci`, then `just security` (audit, licenses). Runs CodeQL analysis separately.
+   - **`release` Job:** Runs _only_ on push to `main` after `test` and `security` pass. Checks out full history, installs dependencies, runs `npx semantic-release` using `GITHUB_TOKEN` and `NPM_TOKEN`.