@williamp29/project-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,153 @@
+# OpenAPI MCP Server
+
+A powerful Model Context Protocol (MCP) server that dynamically explores and interacts with any API defined by an OpenAPI specification.
+
+## For LLM Agents: How to use this MCP
+
+This server provides a set of "meta-tools" that allow you to discover and interact with an API without needing individual tools for every endpoint.
+
+### Recommended Workflow:
+1.  **Discovery**: Start by calling `get_tags` to understand the broad areas of the API.
+2.  **Listing**: Use `get_tag_endpoints` or `get_all_endpoints` to see available actions for a specific topic.
+3.  **Details**: Call `get_endpoint` for a specific path and method to see exactly what parameters and request body are required.
+4.  **Execution**: Use `call_endpoint` to perform the actual API request.
+
+### Identity & Impersonation:
+If the server is configured with an `identity` strategy, you can use `set_identity` to act on behalf of a specific user (e.g., passing a UID).
+
+---
+
+## Installation & Setup
+
+### 1. Build the project
+```bash
+npm install
+npm run build
+```
+
+### 2. Configure Environment Variables
+Create a `.env` file (see `.env.example`):
+- `PROJECT_MCP_API_BASE_URL`: The target API URL.
+- `PROJECT_MCP_AUTH_TYPE`: `bearer`, `identity`, or `none`.
+- `PROJECT_MCP_AUTH_IDENTIFIABLE`: (Optional) e.g., `UID:`.
+- `PROJECT_MCP_AUTH_IDENTIFIER`: Default ID value.
+
+### 3. Usage in Cursor / Claude Desktop
+Add a new MCP server with the following command:
+```bash
+node /path/to/dist/cli.js
+```
+
+Or if installed via npm:
+```bash
+npx @williamp29/project-mcp-server
+```
+
+## Integration in Your Project
+
+The recommended way to use this package is to install it in your project and create a custom entry point.
+
+### Step 1: Install
+```bash
+npm install @williamp29/project-mcp-server
+```
+
+### Step 2: Create your MCP entry file
+Create a file called `mcp-serve.js` (or `.ts`) in your project root:
+
+```javascript
+// mcp-serve.js
+import { MCPServer } from "@williamp29/project-mcp-server";
+import { AuthStrategy, GlobalAuthContext } from "@williamp29/project-mcp-server/api-explorer";
+
+// Your custom authentication logic
+class MyAuth implements AuthStrategy {
+  name = "MyAuth";
+  async getHeaders() {
+    // Read from your own config, database, vault, etc.
+    return { "Authorization": `Bearer ${process.env.MY_API_TOKEN}` };
+  }
+}
+
+const authContext = new GlobalAuthContext(new MyAuth());
+const server = new MCPServer("./openapi-spec.json", authContext);
+server.start();
+```
+
+### Step 3: Add the npm script
+In your project's `package.json`:
+```json
+{
+  "scripts": {
+    "mcp:serve": "node mcp-serve.js"
+  }
+}
+```
+
+### Step 4: Configure Cursor
+In your Cursor MCP settings (`mcp_settings.json`):
+```json
+{
+  "my-api-mcp": {
+    "command": "npm",
+    "args": ["run", "mcp:serve"],
+    "cwd": "/absolute/path/to/your/project"
+  }
+}
+```
+
+Now Cursor will run your custom script whenever it needs to use the MCP server.
+
+---
+
+## Programmatic Usage
+
+If you are using this as a library in your own Node.js project:
+
+### Basic Setup
+```typescript
+import { MCPServer } from "@williamp29/project-mcp-server";
+
+const server = new MCPServer("./openapi-spec.json");
+server.start().catch(console.error);
+```
+
+### Custom Authentication Strategy
+You can implement your own logic for fetching or rotating tokens:
+
+```typescript
+import { MCPServer } from "@williamp29/project-mcp-server";
+import { AuthStrategy, GlobalAuthContext } from "@williamp29/project-mcp-server/api-explorer";
+
+class MyCustomAuth implements AuthStrategy {
+  name = "MyCustomAuth";
+  async getHeaders() {
+    const token = await fetchTokenFromVault();
+    return { "X-Custom-Auth": token };
+  }
+}
+
+const authContext = new GlobalAuthContext(new MyCustomAuth());
+const server = new MCPServer("./spec.json", authContext);
+server.start();
+```
+
+### Request Hooks
+Add custom logic to every request (logging, tracing, extra headers):
+
+```typescript
+import { addRequestHook } from "@williamp29/project-mcp-server/api-explorer";
+
+addRequestHook((config) => {
+  console.error(`[API] ${config.method?.toUpperCase()} ${config.url}`);
+  config.headers["X-Request-ID"] = "mcp-123";
+  return config;
+});
+```
+
+## Features
+- **Dynamic Exploration**: Automatically parses Swagger/OpenAPI 3.0 specs.
+- **Smart Execution**: Handles path parameters (e.g., `{id}`), query strings, and JSON bodies.
+- **Flexible Auth**: Support for standard Bearer tokens and custom Identity headers.
+- **Interceptors**: Easily extendable with request hooks for logging or custom headers.
+- **Impersonation**: Built-in `set_identity` tool to switch users on the fly.

package/dist/api-explorer/api-executor.d.ts

@@ -0,0 +1,39 @@
+import { AuthContext } from "./auth/index.js";
+export interface CallEndpointArgs {
+    method: string;
+    path: string;
+    parameters?: Record<string, any>;
+    body?: any;
+}
+/**
+ * Handles the actual HTTP communication with the API.
+ * Uses axios interceptors to dynamically inject authentication headers and run request hooks.
+ */
+export declare class ApiExecutor {
+    private client;
+    private authContext;
+    /**
+     * @param baseURL - The target API base URL. Defaults to env.PROJECT_MCP_API_BASE_URL.
+     * @param authContext - The AuthContext managing the current authentication strategy.
+     */
+    constructor(baseURL?: string, authContext?: AuthContext);
+    /**
+     * Executes an API request based on the provided meta-tool arguments.
+     * Handles path parameter substitution and query parameter mapping.
+     * @param args - The method, path, and optional parameters/body.
+     */
+    callEndpoint(args: CallEndpointArgs): Promise<{
+        status: number;
+        statusText: string;
+        data: any;
+        error?: undefined;
+        message?: undefined;
+    } | {
+        error: boolean;
+        status: number | undefined;
+        statusText: string | undefined;
+        data: any;
+        message: string;
+    }>;
+    getAuthContext(): AuthContext;
+}

package/dist/api-explorer/api-executor.js

@@ -0,0 +1,87 @@
+import axios from "axios";
+import dotenv from "dotenv";
+import { createAuthContextFromEnv, runRequestHooks } from "./auth/index.js";
+dotenv.config();
+/**
+ * Handles the actual HTTP communication with the API.
+ * Uses axios interceptors to dynamically inject authentication headers and run request hooks.
+ */
+export class ApiExecutor {
+    client;
+    authContext;
+    /**
+     * @param baseURL - The target API base URL. Defaults to env.PROJECT_MCP_API_BASE_URL.
+     * @param authContext - The AuthContext managing the current authentication strategy.
+     */
+    constructor(baseURL, authContext) {
+        const finalBaseURL = baseURL || process.env.PROJECT_MCP_API_BASE_URL || "http://localhost:5000";
+        this.authContext = authContext || createAuthContextFromEnv();
+        this.client = axios.create({
+            baseURL: finalBaseURL,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+        // Add interceptor for dynamic auth and hooks
+        this.client.interceptors.request.use(async (config) => {
+            // 1. Inject Dynamic Auth Headers
+            const authHeaders = await this.authContext.getHeaders();
+            // Log for debugging (stderr)
+            if (Object.keys(authHeaders).length > 0) {
+                console.error(`[ApiExecutor] Injecting auth headers from strategy: ${this.authContext.strategy.name}`);
+            }
+            Object.assign(config.headers, authHeaders);
+            // 2. Run Request Hooks
+            return await runRequestHooks(config);
+        });
+    }
+    /**
+     * Executes an API request based on the provided meta-tool arguments.
+     * Handles path parameter substitution and query parameter mapping.
+     * @param args - The method, path, and optional parameters/body.
+     */
+    async callEndpoint(args) {
+        const { method, path, parameters, body } = args;
+        let renderedPath = path;
+        const queryParams = {};
+        if (parameters) {
+            Object.entries(parameters).forEach(([name, value]) => {
+                const placeholder = `{${name}}`;
+                if (renderedPath.includes(placeholder)) {
+                    renderedPath = renderedPath.replace(placeholder, String(value));
+                }
+                else {
+                    queryParams[name] = value;
+                }
+            });
+        }
+        try {
+            const response = await this.client.request({
+                method: method.toUpperCase(),
+                url: renderedPath,
+                params: queryParams,
+                data: body,
+            });
+            return {
+                status: response.status,
+                statusText: response.statusText,
+                data: response.data,
+            };
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                return {
+                    error: true,
+                    status: error.response?.status,
+                    statusText: error.response?.statusText,
+                    data: error.response?.data,
+                    message: error.message,
+                };
+            }
+            throw error;
+        }
+    }
+    getAuthContext() {
+        return this.authContext;
+    }
+}

package/dist/api-explorer/auth/auth-context.d.ts

@@ -0,0 +1,16 @@
+import { AuthContext, AuthStrategy } from "./types.js";
+/**
+ * Standard implementation of AuthContext that wraps an AuthStrategy.
+ * Handles runtime identifier updates for identity-based strategies.
+ */
+export declare class GlobalAuthContext implements AuthContext {
+    strategy: AuthStrategy;
+    /**
+     * @param strategy - The initial authentication strategy to use.
+     */
+    constructor(strategy: AuthStrategy);
+    setIdentifier(value: string): void;
+    getIdentifier(): string;
+    getHeaders(): Promise<Record<string, string>>;
+}
+export declare function createAuthContextFromEnv(): AuthContext;

package/dist/api-explorer/auth/auth-context.js

@@ -0,0 +1,52 @@
+import { BearerStrategy } from "./strategies/bearer-strategy.js";
+import { IdentityStrategy } from "./strategies/identity-strategy.js";
+import { NoAuthStrategy } from "./strategies/no-auth-strategy.js";
+import dotenv from "dotenv";
+dotenv.config();
+/**
+ * Standard implementation of AuthContext that wraps an AuthStrategy.
+ * Handles runtime identifier updates for identity-based strategies.
+ */
+export class GlobalAuthContext {
+    strategy;
+    /**
+     * @param strategy - The initial authentication strategy to use.
+     */
+    constructor(strategy) {
+        this.strategy = strategy;
+    }
+    setIdentifier(value) {
+        if (this.strategy instanceof IdentityStrategy) {
+            this.strategy.setIdentifier(value);
+        }
+        else {
+            console.error(`Current strategy ${this.strategy.name} does not support setting an identifier.`);
+        }
+    }
+    getIdentifier() {
+        if (this.strategy instanceof IdentityStrategy) {
+            return this.strategy.getIdentifier();
+        }
+        return "";
+    }
+    async getHeaders() {
+        return await this.strategy.getHeaders();
+    }
+}
+export function createAuthContextFromEnv() {
+    const authType = process.env.PROJECT_MCP_AUTH_TYPE || "bearer";
+    let strategy;
+    switch (authType.toLowerCase()) {
+        case "identity":
+            strategy = new IdentityStrategy(process.env.PROJECT_MCP_AUTH_HEADER_KEY || "Authorization", process.env.PROJECT_MCP_AUTH_IDENTIFIABLE || "UID:", process.env.PROJECT_MCP_AUTH_IDENTIFIER || "");
+            break;
+        case "bearer":
+            strategy = new BearerStrategy(process.env.PROJECT_MCP_API_BEARER_TOKEN || "");
+            break;
+        case "none":
+        default:
+            strategy = new NoAuthStrategy();
+            break;
+    }
+    return new GlobalAuthContext(strategy);
+}

package/dist/api-explorer/auth/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./auth-context.js";
+export * from "./request-hooks.js";
+export * from "./strategies/bearer-strategy.js";
+export * from "./strategies/identity-strategy.js";
+export * from "./strategies/no-auth-strategy.js";

package/dist/api-explorer/auth/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./auth-context.js";
+export * from "./request-hooks.js";
+export * from "./strategies/bearer-strategy.js";
+export * from "./strategies/identity-strategy.js";
+export * from "./strategies/no-auth-strategy.js";

package/dist/api-explorer/auth/request-hooks.d.ts

@@ -0,0 +1,16 @@
+import { RequestHook } from "./types.js";
+import { InternalAxiosRequestConfig } from "axios";
+/**
+ * Registers a new hook to be run before every outgoing API request.
+ * Hooks can be used to log, trace, or modify the request configuration.
+ */
+export declare function addRequestHook(hook: RequestHook): void;
+/**
+ * Executes all registered request hooks in the order they were added.
+ * @param config - The axios request configuration.
+ */
+export declare function runRequestHooks(config: InternalAxiosRequestConfig): Promise<InternalAxiosRequestConfig>;
+/**
+ * Removes all registered request hooks. Useful for testing or resets.
+ */
+export declare function clearRequestHooks(): void;

package/dist/api-explorer/auth/request-hooks.js

@@ -0,0 +1,25 @@
+const hooks = [];
+/**
+ * Registers a new hook to be run before every outgoing API request.
+ * Hooks can be used to log, trace, or modify the request configuration.
+ */
+export function addRequestHook(hook) {
+    hooks.push(hook);
+}
+/**
+ * Executes all registered request hooks in the order they were added.
+ * @param config - The axios request configuration.
+ */
+export async function runRequestHooks(config) {
+    let currentConfig = config;
+    for (const hook of hooks) {
+        currentConfig = await hook(currentConfig);
+    }
+    return currentConfig;
+}
+/**
+ * Removes all registered request hooks. Useful for testing or resets.
+ */
+export function clearRequestHooks() {
+    hooks.length = 0;
+}

package/dist/api-explorer/auth/strategies/bearer-strategy.d.ts

@@ -0,0 +1,10 @@
+import { AuthStrategy } from "../types.js";
+/**
+ * Authentication strategy that uses a standard Authorization: Bearer <token> header.
+ */
+export declare class BearerStrategy implements AuthStrategy {
+    private token;
+    name: string;
+    constructor(token: string);
+    getHeaders(): Record<string, string>;
+}

package/dist/api-explorer/auth/strategies/bearer-strategy.js

@@ -0,0 +1,17 @@
+/**
+ * Authentication strategy that uses a standard Authorization: Bearer <token> header.
+ */
+export class BearerStrategy {
+    token;
+    name = "Bearer";
+    constructor(token) {
+        this.token = token;
+    }
+    getHeaders() {
+        if (!this.token)
+            return {};
+        return {
+            Authorization: `Bearer ${this.token}`,
+        };
+    }
+}

package/dist/api-explorer/auth/strategies/identity-strategy.d.ts

@@ -0,0 +1,15 @@
+import { AuthStrategy } from "../types.js";
+/**
+ * Highly flexible authentication strategy for custom headers and identifiers.
+ * Useful for scenarios like "Authorization: UID <identifier>" or "X-API-Key: <key>".
+ */
+export declare class IdentityStrategy implements AuthStrategy {
+    private headerKey;
+    private identifiable;
+    name: string;
+    private currentIdentifier;
+    constructor(headerKey: string, identifiable: string, initialIdentifier: string);
+    setIdentifier(value: string): void;
+    getIdentifier(): string;
+    getHeaders(): Record<string, string>;
+}

package/dist/api-explorer/auth/strategies/identity-strategy.js

@@ -0,0 +1,31 @@
+/**
+ * Highly flexible authentication strategy for custom headers and identifiers.
+ * Useful for scenarios like "Authorization: UID <identifier>" or "X-API-Key: <key>".
+ */
+export class IdentityStrategy {
+    headerKey;
+    identifiable;
+    name = "Identity";
+    currentIdentifier;
+    constructor(headerKey, identifiable, initialIdentifier) {
+        this.headerKey = headerKey;
+        this.identifiable = identifiable;
+        this.currentIdentifier = initialIdentifier;
+    }
+    setIdentifier(value) {
+        this.currentIdentifier = value;
+    }
+    getIdentifier() {
+        return this.currentIdentifier;
+    }
+    getHeaders() {
+        if (!this.currentIdentifier)
+            return {};
+        const value = this.identifiable
+            ? `${this.identifiable} ${this.currentIdentifier}`
+            : this.currentIdentifier;
+        return {
+            [this.headerKey]: value,
+        };
+    }
+}

package/dist/api-explorer/auth/strategies/no-auth-strategy.d.ts

@@ -0,0 +1,8 @@
+import { AuthStrategy } from "../types.js";
+/**
+ * Strategy for APIs that do not require any authentication.
+ */
+export declare class NoAuthStrategy implements AuthStrategy {
+    name: string;
+    getHeaders(): Record<string, string>;
+}

package/dist/api-explorer/auth/strategies/no-auth-strategy.js

@@ -0,0 +1,9 @@
+/**
+ * Strategy for APIs that do not require any authentication.
+ */
+export class NoAuthStrategy {
+    name = "None";
+    getHeaders() {
+        return {};
+    }
+}

package/dist/api-explorer/auth/types.d.ts

@@ -0,0 +1,25 @@
+import { InternalAxiosRequestConfig } from "axios";
+/**
+ * Interface for authentication strategies that provide HTTP headers.
+ */
+export interface AuthStrategy {
+    name: string;
+    /**
+     * Returns a dictionary of headers to be injected into the request.
+     */
+    getHeaders(): Record<string, string> | Promise<Record<string, string>>;
+}
+/**
+ * Manages the current authentication state and allows dynamic identifier updates.
+ */
+export interface AuthContext {
+    strategy: AuthStrategy;
+    /**
+     * Updates the user identifier (e.g. for impersonation).
+     * @param value - The new identifier value.
+     */
+    setIdentifier(value: string): void;
+    getIdentifier(): string;
+    getHeaders(): Promise<Record<string, string>>;
+}
+export type RequestHook = (config: InternalAxiosRequestConfig) => InternalAxiosRequestConfig | Promise<InternalAxiosRequestConfig>;

package/dist/api-explorer/auth/types.js

@@ -0,0 +1 @@
+export {};

package/dist/api-explorer/index.d.ts

@@ -0,0 +1,4 @@
+export { OpenAPIParser } from "./openapi-parser.js";
+export { ToolGenerator } from "./tool-generator.js";
+export { ApiExecutor } from "./api-executor.js";
+export * from "./auth/index.js";

package/dist/api-explorer/index.js

@@ -0,0 +1,6 @@
+// API Explorer module exports
+export { OpenAPIParser } from "./openapi-parser.js";
+export { ToolGenerator } from "./tool-generator.js";
+export { ApiExecutor } from "./api-executor.js";
+// Auth exports
+export * from "./auth/index.js";

package/dist/api-explorer/openapi-parser.d.ts

@@ -0,0 +1,31 @@
+import { OpenAPI } from "openapi-types";
+export interface Endpoint {
+    method: string;
+    path: string;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    parameters?: any[];
+    requestBody?: any;
+    responses?: any;
+}
+/**
+ * Service responsible for loading, parsing, and extracting data from OpenAPI specifications.
+ * Uses @apidevtools/swagger-parser for robust dereferencing and validation.
+ */
+export declare class OpenAPIParser {
+    private spec;
+    private endpoints;
+    /**
+     * Loads and parses an OpenAPI specification from the given file path.
+     * @param specPath - Absolute path to the openapi-spec.json file.
+     */
+    loadSpec(specPath: string): Promise<void>;
+    getSpec(): OpenAPI.Document;
+    getTags(): string[];
+    getEndpoints(): Endpoint[];
+    getEndpointsByTag(tag: string): Endpoint[];
+    getEndpointsByTags(tags: string[]): Endpoint[];
+    getEndpoint(method: string, path: string): Endpoint | undefined;
+}

package/dist/api-explorer/openapi-parser.js

@@ -0,0 +1,83 @@
+import SwaggerParser from "@apidevtools/swagger-parser";
+/**
+ * Service responsible for loading, parsing, and extracting data from OpenAPI specifications.
+ * Uses @apidevtools/swagger-parser for robust dereferencing and validation.
+ */
+export class OpenAPIParser {
+    spec = null;
+    endpoints = [];
+    /**
+     * Loads and parses an OpenAPI specification from the given file path.
+     * @param specPath - Absolute path to the openapi-spec.json file.
+     */
+    async loadSpec(specPath) {
+        try {
+            this.spec = await SwaggerParser.dereference(specPath);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse OpenAPI spec: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    getSpec() {
+        if (!this.spec) {
+            throw new Error("Spec not loaded. Call loadSpec() first.");
+        }
+        return this.spec;
+    }
+    getTags() {
+        const spec = this.getSpec();
+        const tags = new Set();
+        if ('tags' in spec && spec.tags) {
+            spec.tags.forEach((tag) => tags.add(tag.name));
+        }
+        if ('paths' in spec && spec.paths) {
+            Object.entries(spec.paths).forEach(([path, pathItem]) => {
+                if (!pathItem)
+                    return;
+                ['get', 'post', 'put', 'delete', 'patch'].forEach((method) => {
+                    const operation = pathItem[method];
+                    if (operation && operation.tags) {
+                        operation.tags.forEach((tag) => tags.add(tag));
+                    }
+                });
+            });
+        }
+        return Array.from(tags).sort();
+    }
+    getEndpoints() {
+        const spec = this.getSpec();
+        const endpoints = [];
+        if ('paths' in spec && spec.paths) {
+            Object.entries(spec.paths).forEach(([path, pathItem]) => {
+                if (!pathItem)
+                    return;
+                ['get', 'post', 'put', 'delete', 'patch'].forEach((method) => {
+                    const operation = pathItem[method];
+                    if (operation) {
+                        endpoints.push({
+                            method: method.toUpperCase(),
+                            path,
+                            operationId: operation.operationId,
+                            summary: operation.summary,
+                            description: operation.description,
+                            tags: operation.tags,
+                            parameters: operation.parameters,
+                            requestBody: operation.requestBody,
+                            responses: operation.responses,
+                        });
+                    }
+                });
+            });
+        }
+        return endpoints;
+    }
+    getEndpointsByTag(tag) {
+        return this.getEndpoints().filter((endpoint) => endpoint.tags?.includes(tag));
+    }
+    getEndpointsByTags(tags) {
+        return this.getEndpoints().filter((endpoint) => endpoint.tags?.some((t) => tags.includes(t)));
+    }
+    getEndpoint(method, path) {
+        return this.getEndpoints().find((e) => e.method === method.toUpperCase() && e.path === path);
+    }
+}

package/dist/api-explorer/tool-generator.d.ts

@@ -0,0 +1,68 @@
+import { OpenAPIParser } from "./openapi-parser.js";
+import { z } from "zod";
+export interface ToolConfig {
+    name: string;
+    description: string;
+    inputSchema?: z.ZodType<any>;
+}
+/**
+ * Service that maps OpenAPI endpoints to MCP-compatible tool definitions.
+ * It provides the metadata for tools that an LLM can use to explore and interact with the API.
+ */
+export declare class ToolGenerator {
+    private parser;
+    /**
+     * @param parser - The OpenAPIParser instance containing the parsed spec.
+     */
+    constructor(parser: OpenAPIParser);
+    /**
+     * Returns a dictionary of tool definitions with their descriptions and Zod input schemas.
+     * These definitions are used by MCPServer to register tools with the SDK.
+     */
+    getToolDefinitions(): {
+        get_tags: {
+            description: string;
+        };
+        get_tag_endpoints: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                tag: z.ZodString;
+            }, z.core.$strip>;
+        };
+        get_tags_endpoints: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                tags: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+        };
+        get_all_endpoints: {
+            description: string;
+        };
+        get_endpoint: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                method: z.ZodString;
+                path: z.ZodString;
+            }, z.core.$strip>;
+        };
+        get_endpoints: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                requests: z.ZodArray<z.ZodObject<{
+                    method: z.ZodString;
+                    path: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        };
+        call_endpoint: {
+            description: string;
+            inputSchema: z.ZodObject<{
+                method: z.ZodString;
+                path: z.ZodString;
+                parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+                body: z.ZodOptional<z.ZodAny>;
+            }, z.core.$strip>;
+        };
+    };
+    handleToolCall(name: string, args: any): any;
+}

package/dist/api-explorer/tool-generator.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+/**
+ * Service that maps OpenAPI endpoints to MCP-compatible tool definitions.
+ * It provides the metadata for tools that an LLM can use to explore and interact with the API.
+ */
+export class ToolGenerator {
+    parser;
+    /**
+     * @param parser - The OpenAPIParser instance containing the parsed spec.
+     */
+    constructor(parser) {
+        this.parser = parser;
+    }
+    /**
+     * Returns a dictionary of tool definitions with their descriptions and Zod input schemas.
+     * These definitions are used by MCPServer to register tools with the SDK.
+     */
+    getToolDefinitions() {
+        return {
+            get_tags: {
+                description: "Get all unique tags defined in the API spec. This helps to group and discover endpoints.",
+            },
+            get_tag_endpoints: {
+                description: "Get all endpoints associated with a specific tag. Returns a summary of each endpoint.",
+                inputSchema: z.object({
+                    tag: z.string().describe("The tag to filter endpoints by."),
+                }),
+            },
+            get_tags_endpoints: {
+                description: "Get all endpoints associated with multiple tags. Returns a summary of each endpoint.",
+                inputSchema: z.object({
+                    tags: z.array(z.string()).describe("The tags to filter endpoints by."),
+                }),
+            },
+            get_all_endpoints: {
+                description: "Get a summarized list of all endpoints available in the API.",
+            },
+            get_endpoint: {
+                description: "Get detailed information about a specific endpoint, including parameters and request body schema.",
+                inputSchema: z.object({
+                    method: z.string().describe("The HTTP method (GET, POST, etc.)."),
+                    path: z.string().describe("The endpoint path."),
+                }),
+            },
+            get_endpoints: {
+                description: "Get detailed information for multiple specific endpoints.",
+                inputSchema: z.object({
+                    requests: z.array(z.object({
+                        method: z.string(),
+                        path: z.string(),
+                    })).describe("List of endpoint requests."),
+                }),
+            },
+            call_endpoint: {
+                description: "Execute a request to a project's endpoint using the specified parameters and body.",
+                inputSchema: z.object({
+                    method: z.string().describe("The HTTP method."),
+                    path: z.string().describe("The endpoint path (e.g., /projects/{id})."),
+                    parameters: z.record(z.string(), z.any()).optional().describe("Path and query parameters (mapped by name)."),
+                    body: z.any().optional().describe("The request body payload."),
+                }),
+            },
+        };
+    }
+    handleToolCall(name, args) {
+        switch (name) {
+            case "get_tags":
+                return this.parser.getTags();
+            case "get_tag_endpoints":
+                return this.parser.getEndpointsByTag(args.tag);
+            case "get_tags_endpoints":
+                return this.parser.getEndpointsByTags(args.tags);
+            case "get_all_endpoints":
+                return this.parser.getEndpoints();
+            case "get_endpoint":
+                return this.parser.getEndpoint(args.method, args.path);
+            case "get_endpoints":
+                return args.requests.map((r) => this.parser.getEndpoint(r.method, r.path));
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { MCPServer } from "./index.js";
+import path from "path";
+import { fileURLToPath } from "url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SPEC_PATH = path.resolve(__dirname, "../openapi-spec.json");
+const specPath = process.argv[2] || DEFAULT_SPEC_PATH;
+const server = new MCPServer(specPath);
+server.start().catch((error) => {
+    console.error("Fatal error in MCP server:", error);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { MCPServer } from "./mcp-server.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { MCPServer } from "./mcp-server.js";

package/dist/mcp-server.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The main MCP Server implementation that coordinates the OpenAPI parser,
+ * tool generation, and API execution.
+ *
+ * It registers meta-tools that allow LLMs to:
+ * 1. Discover API structure (tags, endpoints, schemas).
+ * 2. Execute calls to any endpoint with dynamic authentication.
+ * 3. Impersonate users via the set_identity tool.
+ */
+export declare class MCPServer {
+    private specPath;
+    private server;
+    private parser;
+    private toolGenerator;
+    private apiExecutor;
+    private authContext;
+    constructor(specPath: string);
+    private initParser;
+    private registerTools;
+    /**
+     * Starts the MCP server on Stdio transport.
+     * This method ensures the OpenAPI spec is loaded and tools are registered before connecting.
+     */
+    start(): Promise<void>;
+}

package/dist/mcp-server.js

@@ -0,0 +1,103 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { OpenAPIParser } from "./api-explorer/openapi-parser.js";
+import { ToolGenerator } from "./api-explorer/tool-generator.js";
+import { ApiExecutor } from "./api-explorer/api-executor.js";
+import { createAuthContextFromEnv } from "./api-explorer/auth/index.js";
+/**
+ * The main MCP Server implementation that coordinates the OpenAPI parser,
+ * tool generation, and API execution.
+ *
+ * It registers meta-tools that allow LLMs to:
+ * 1. Discover API structure (tags, endpoints, schemas).
+ * 2. Execute calls to any endpoint with dynamic authentication.
+ * 3. Impersonate users via the set_identity tool.
+ */
+export class MCPServer {
+    specPath;
+    server;
+    parser;
+    toolGenerator;
+    apiExecutor;
+    authContext;
+    constructor(specPath) {
+        this.specPath = specPath;
+        this.parser = new OpenAPIParser();
+        this.toolGenerator = new ToolGenerator(this.parser);
+        this.authContext = createAuthContextFromEnv();
+        this.apiExecutor = new ApiExecutor(undefined, this.authContext);
+        this.server = new McpServer({
+            name: "project-mcp-server",
+            version: "1.0.0",
+        });
+    }
+    async initParser() {
+        try {
+            await this.parser.loadSpec(this.specPath);
+            console.error(`Loaded OpenAPI spec from ${this.specPath}`);
+            this.registerTools();
+        }
+        catch (error) {
+            console.error(`Failed to load OpenAPI spec: ${error}`);
+            process.exit(1);
+        }
+    }
+    registerTools() {
+        const definitions = this.toolGenerator.getToolDefinitions();
+        Object.entries(definitions).forEach(([name, def]) => {
+            this.server.registerTool(name, {
+                description: def.description,
+                inputSchema: def.inputSchema,
+            }, async (args) => {
+                try {
+                    let result;
+                    if (name === "call_endpoint") {
+                        result = await this.apiExecutor.callEndpoint(args);
+                    }
+                    else {
+                        result = this.toolGenerator.handleToolCall(name, args);
+                    }
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [{ type: "text", text: `Error: ${error.message}` }],
+                        isError: true,
+                    };
+                }
+            });
+        });
+        this.server.registerTool("set_identity", {
+            description: "Set the identity (identifier) for future API requests. Requires an 'identity' auth strategy to be active.",
+            inputSchema: z.object({
+                identifier: z.string().describe("The new identity value (e.g., user UID)."),
+            }),
+        }, async ({ identifier }) => {
+            try {
+                this.authContext.setIdentifier(identifier);
+                return {
+                    content: [{ type: "text", text: `Successfully updated identity to: ${identifier}` }],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [{ type: "text", text: `Error: ${error.message}` }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    /**
+     * Starts the MCP server on Stdio transport.
+     * This method ensures the OpenAPI spec is loaded and tools are registered before connecting.
+     */
+    async start() {
+        await this.initParser();
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("OpenAPI MCP server running on stdio");
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@williamp29/project-mcp-server",
+  "version": "1.0.0",
+  "description": "A ModelContextProtocol server to let agents discover your project, such as APIs (using OpenAPI) or other resources.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "project-mcp-server": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./api-explorer": {
+      "types": "./dist/api-explorer/index.d.ts",
+      "import": "./dist/api-explorer/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "ts-node src/cli.ts",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@modelcontextprotocol/inspector": "^0.18.0",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "axios": "^1.13.2",
+    "dotenv": "^17.2.3",
+    "g": "^2.0.1",
+    "openapi-types": "^12.1.3",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.9",
+    "@types/node-fetch": "^2.6.13",
+    "@types/swagger-parser": "^4.0.3",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}