@avidian/mcp-openapi 0.1.2 → 0.2.0

package/README.md

@@ -1,16 +1,14 @@
 # @avidian/mcp-openapi
 
-MCP server for OpenAPI/Swagger — gives AI agents the ability to discover, search, and call any REST API described by an OpenAPI or Swagger document.
+MCP server for OpenAPI/Swagger.
+It lets an AI agent discover, inspect, and call any REST API described by an OpenAPI or Swagger document, while keeping the agent's context footprint small.
 
-Point it at a single OpenAPI/Swagger document (URL or local file, 2.0/3.0/3.1) and it exposes:
-
-- The full, dereferenced document as a readable MCP resource
-- A keyword search tool for finding the right operation when a spec defines many of them
-- One MCP tool per operation, which proxies a real HTTP request to the underlying API
+Instead of registering one MCP tool per API operation (which pushes every operation's schema into the agent's context up front), this server exposes a small, fixed set of generic **meta-tools**.
+The agent loads one or more specs at runtime, searches and inspects their operations on demand, and executes them - all through the same six tools, no matter how large or how many specs are loaded.
 
 ## Installation
 
-### npm (requires Node.js ≥ 20)
+### npm (requires Node.js >= 20)
 
 ```bash
 npm install -g @avidian/mcp-openapi
@@ -20,27 +18,79 @@ npm install -g @avidian/mcp-openapi
 
 Download from [GitHub Releases](https://github.com/avidianity/mcp-openapi/releases).
 
+## How it works
+
+The server holds an in-memory registry of loaded **specs**.
+Each loaded spec is a single OpenAPI/Swagger document (2.0, 3.0, or 3.1) together with its parsed operations, and is identified by a **spec id** - a lowercase [ULID](https://github.com/ulid/spec) the server generates automatically.
+The agent discovers spec ids by listing what is loaded, then passes an id to the other tools.
+Nothing is persisted: a restart starts fresh and re-runs any startup preloads.
+
+### Meta-tools
+
+The server registers exactly these six tools, and never one tool per operation:
+
+| Tool                 | What it does                                                                                                                  |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `load_spec`          | Load a spec from a URL, a local file path, or inline JSON/YAML content. Returns a generated spec id and a compact summary.    |
+| `list_specs`         | List every loaded spec with its id and summary.                                                                               |
+| `unload_spec`        | Remove a loaded spec, freeing its operations and cached search index.                                                         |
+| `search_operations`  | Search (or, with no query, browse) a spec's operations. Returns compact one-liners; use `describe_operation` for full detail. |
+| `describe_operation` | Return one operation's parameters and request-body schema in full, plus a summarized view of its responses.                   |
+| `execute_operation`  | Perform the real HTTP request for one operation, with arguments grouped by location (path, query, headers, body).             |
+
+Operations are referenced by their `method` and `path` (for example `get` and `/pets/{petId}`), exactly as `search_operations` reports them.
+
 ## Usage
 
-```bash
-mcp-openapi <openapi-url-or-path> [--base-url <url>] [--timeout <ms>]
-```
+The server can start empty and let the agent load everything at runtime, or preload one or more specs at startup.
 
 ```bash
+# Start empty; the agent calls load_spec at runtime.
+mcp-openapi
+
+# Preload a single spec (the common case).
 mcp-openapi https://petstore3.swagger.io/api/v3/openapi.json
 mcp-openapi ./openapi.yaml --base-url https://api.internal.example.com --timeout 10000
+
+# Preload several specs, each with its own settings, from a config file.
+mcp-openapi --config ./specs.json
+```
+
+CLI shape:
+
+```
+mcp-openapi [<source>] [--base-url <url>] [--credential <name>] [--timeout <ms>] [--config <path>]
 ```
 
-The source may also come from `OPENAPI_URL` instead of the positional argument, which is convenient for MCP client configs.
+The single positional `<source>` may also come from `OPENAPI_URL`, which is convenient for MCP client configs.
+
+### Config file
+
+A JSON config file preloads any number of specs, each with an optional per-spec base URL and credential reference:
+
+```json
+{
+  "specs": [
+    { "source": "https://api.example.com/openapi.json", "credential": "example" },
+    { "source": "./internal.yaml", "base_url": "https://api.internal.example.com" }
+  ],
+  "max_specs": 20,
+  "request_timeout_ms": 30000,
+  "max_response_bytes": 100000
+}
+```
+
+Unknown keys are rejected so typos surface.
+A preload that fails to load is logged to stderr and skipped; the server still starts, and the agent can load specs at runtime.
 
 ### MCP client configuration
 
 ```json
 {
   "mcpServers": {
-    "my-api": {
+    "openapi": {
       "command": "mcp-openapi",
-      "args": ["https://api.example.com/openapi.json"]
+      "args": ["--config", "/path/to/specs.json"]
     }
   }
 }
@@ -48,29 +98,52 @@ The source may also come from `OPENAPI_URL` instead of the positional argument,
 
 ## Configuration
 
-| Variable                     | Description                                                                   |
-| ---------------------------- | ----------------------------------------------------------------------------- |
-| `OPENAPI_URL`                | OpenAPI/Swagger source (URL or local path), if not passed as the CLI argument |
-| `OPENAPI_BASE_URL`           | Overrides every server URL declared in the spec                               |
-| `OPENAPI_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds (default `30000`)                         |
+| Variable                     | Description                                                                                           |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `OPENAPI_CONFIG`             | Path to a JSON config file listing specs to preload                                                   |
+| `OPENAPI_URL`                | Single spec source (URL, local path, or inline content) to preload, if not passed as the CLI argument |
+| `OPENAPI_BASE_URL`           | Base URL override for the `OPENAPI_URL` / positional spec                                             |
+| `OPENAPI_CREDENTIAL`         | Credential reference name for the `OPENAPI_URL` / positional spec                                     |
+| `OPENAPI_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds (default `30000`)                                                 |
+| `OPENAPI_MAX_RESPONSE_BYTES` | Cap on response bytes read from an upstream API (default `100000`)                                    |
+| `OPENAPI_MAX_SPECS`          | Maximum number of specs that may be loaded at once (default `20`)                                     |
+
+Precedence for these knobs is: environment variable > config file > default.
+The request timeout additionally accepts the `--timeout` CLI flag, which wins over the environment variable; the response cap and max-specs knobs have no CLI flag.
 
 ### Authentication
 
-For each security scheme declared in the OpenAPI document, credentials are read from environment variables named after the scheme (converted to `SCREAMING_SNAKE_CASE`) — e.g. a scheme called `apiKeyAuth` reads `OPENAPI_AUTH_API_KEY_AUTH`.
+Credentials are always provisioned by the operator in the environment and resolved server-side; a secret value never passes through the agent.
+
+The recommended approach is **credential references**.
+The operator provisions a secret under a reference name, and the agent (or config file) passes only that name to `load_spec`:
+
+| Scheme type                    | Environment variables (for reference name `<REF>`)              |
+| ------------------------------ | --------------------------------------------------------------- |
+| HTTP bearer                    | `OPENAPI_CRED_<REF>_TOKEN` (or bare `OPENAPI_CRED_<REF>`)       |
+| HTTP basic                     | `OPENAPI_CRED_<REF>_USERNAME` and `OPENAPI_CRED_<REF>_PASSWORD` |
+| apiKey (header, query, cookie) | `OPENAPI_CRED_<REF>`                                            |
 
-| Scheme type                    | Environment variables                                                 |
+For example, provisioning `OPENAPI_CRED_GITHUB_TOKEN` and loading with `credential: "github"` applies that token to the spec's security scheme(s).
+A reference is applied only to the schemes named in the document's `security` requirement, so one secret is not sprayed across unrelated schemes.
+(When the document declares no top-level `security`, the reference is applied to every scheme it defines.)
+
+When no `credential` is given, the server falls back to matching each of the document's security schemes by name (converted to `SCREAMING_SNAKE_CASE`):
+
+| Scheme type                    | Environment variables (for scheme `<SCHEME>`)                         |
 | ------------------------------ | --------------------------------------------------------------------- |
 | HTTP bearer                    | `OPENAPI_AUTH_<SCHEME>_TOKEN` (or bare `OPENAPI_AUTH_<SCHEME>`)       |
 | HTTP basic                     | `OPENAPI_AUTH_<SCHEME>_USERNAME` and `OPENAPI_AUTH_<SCHEME>_PASSWORD` |
 | apiKey (header, query, cookie) | `OPENAPI_AUTH_<SCHEME>`                                               |
 
-Schemes with no matching environment variable, and unsupported types (OAuth2, OpenID Connect), are skipped with a warning rather than failing startup.
+Schemes with no matching environment variable are skipped silently; unsupported types (OAuth2, OpenID Connect) are skipped with a warning.
+Neither case fails startup.
 
-## What it exposes
+### Security note
 
-- **Resource** `openapi://spec` — the full, dereferenced OpenAPI/Swagger document.
-- **Tool** `search_operations` — keyword search across every operation's name, summary, description, tags, and path. Use this first when a spec defines many operations.
-- **One tool per operation** — named after its `operationId` (sanitized and deduplicated), taking the operation's path/query/header parameters and request body as arguments.
+`load_spec` fetches whatever URL or reads whatever local file the agent asks it to, and `execute_operation` calls the base URL declared by (or overridden for) a loaded spec, attaching the operator-provisioned credentials.
+This is intrinsic to the tool's purpose, but it means a spec pointing at an internal or metadata endpoint would be fetched and called from wherever the server runs.
+Run the server in an environment where that request surface is acceptable, and only provision credentials for APIs you intend the agent to call.
 
 ## Development
 
@@ -79,7 +152,7 @@ Schemes with no matching environment variable, and unsupported types (OAuth2, Op
 bun install
 
 # Run in dev mode
-bun run dev <openapi-url-or-path>
+bun run dev [<source>]
 
 # Type check
 bun run typecheck
@@ -93,6 +166,9 @@ bun run format
 # Test
 bun run test
 
+# Everything the CI gate runs
+bun run check
+
 # Build for npm
 bun run build
 
@@ -100,7 +176,9 @@ bun run build
 bun run compile
 ```
 
-`ajv` is listed as a direct devDependency even though nothing in `src/` imports it. It's a workaround: `@apidevtools/swagger-parser` depends on `ajv-draft-04`, which only declares `ajv` as a peer dependency, and Bun's bundler fails to statically resolve that peer dependency when producing standalone binaries (`bun run compile`) unless `ajv` is also resolvable as a direct dependency somewhere in the root of the tree. Not needed for `bun run build` (the npm-published bundle), which keeps `@apidevtools/swagger-parser` external and lets Node resolve it normally at install time.
+`ajv` is listed as a direct devDependency even though nothing in `src/` imports it.
+It's a workaround: `@apidevtools/swagger-parser` depends on `ajv-draft-04`, which only declares `ajv` as a peer dependency, and Bun's bundler fails to statically resolve that peer dependency when producing standalone binaries (`bun run compile`) unless `ajv` is also resolvable as a direct dependency somewhere in the root of the tree.
+Not needed for `bun run build` (the npm-published bundle), which keeps `@apidevtools/swagger-parser` external and lets Node resolve it normally at install time.
 
 ## License