{
  "markdown": "<h1 align=\"center\">\n  SpecRun\n</h1>\nAn MCP server that turns OpenAPI specifications into MCP tools. Scans a folder for OpenAPI spec files and automatically generate corresponding tools. These tools can then be used in any MCP client to interact with the APIs defined by the specs, with built-in support for authentication and server URL management via a simple `.env` file.\n\nBuilt with [FastMCP](https://www.npmjs.com/package/fastmcp) for TypeScript.\n\n## ✨ Features\n\n- **Zero Configuration**: Filesystem is the interface - just drop OpenAPI specs in a folder\n- **Supports OpenAPI 3.0 and 2.0**: Works with both OpenAPI 3.x and Swagger 2.0 specs\n- **Namespace Isolation**: Multiple APIs coexist cleanly\n- **Full OpenAPI Support**: Handles parameters, request bodies, authentication, and responses\n- **Run Any Tool to Interact with APIs**: For example, `cars_addCar` to call `POST /cars` from `cars.json` spec to create a new car, or `github_get_user_repos` to call `GET /user/repos` from `github.yaml` spec to list repos.\n- **Run Any Tool with Custom Inputs**: Pass structured JSON inputs for parameters and request bodies\n- **Run Any Tool to see Spec Details**: Get the original OpenAPI spec details for any tool, including parameters, request body schema, and response schema\n- **Run Any Tool to get API responses as resources**: Each tool call returns a JSON resource containing request URL, request body, and response\n- **Run Any Tool in Batch**: One `specrun_batch` tool can execute any tool with multiple inputs and returns a consolidated JSON resource\n- **Auto Authentication**: Simple `.env` file with `{API_NAME}_API_KEY` pattern\n- **Auto .env Placeholders**: Adds `{API_NAME}_SERVER_URL` and `{API_NAME}_BEARER_TOKEN` entries when missing\n- **Multiple Transports**: Support for stdio and HTTP streaming\n- **Built-in Debugging**: List command to see loaded specs and tools\n- **MCP Prompts**: Built-in prompts for listing tools, generating inputs, and explaining schemas\n- **Agent**: configured agent for using SpecRun tools to explore and operate APIs in a guided way ([`.github/agents/specrun.agent.md`](.github/agents/specrun.agent.md))\n\n## Quick Start\n\n### Requirements\n\n- Node.js 22 or newer\n\n### 1️⃣ Install (optional)\n\n```bash\nnpm install -g specrun\n```\n\n### 2️⃣ Create a specs folder where the server can read OpenAPI spec files. For example:\n\n```bash\nmkdir ~/specs\n```\n\n### 3️⃣ Add OpenAPI specs\n\nDrop any `.json`, `.yaml`, or `.yml` OpenAPI specification files into your specs folder\n\n### 4️⃣ Configure authentication (optional)\n\nCreate a `.env` file in your specs folder:\n\n```bash\n# ~/specs/.env\nCARS_API_KEY=your_api_key_here\n```\n\nSpecRun will also ensure `{API_NAME}_SERVER_URL` and `{API_NAME}_BEARER_TOKEN` entries exist for each spec, adding empty placeholders when missing.\nWhen `{API_NAME}_SERVER_URL` has a value, SpecRun updates the spec file on load:\n\n- OpenAPI 3.0: updates the first `servers` entry.\n- OpenAPI 2.0 (formerly Swagger 2.0): updates `host`, `schemes`, and `basePath` (no `servers` section in OpenAPI 2.0).\n\nSpecRun also watches the `.env` file and refreshes server URLs and auth config automatically after changes.\n\n### 5️⃣ Add to MCP client configuration\n\nAdd to your MCP configuration:\n\nIf installed on your machine:\n\n```json\n{\n  \"mcpServers\": {\n    \"specrun\": {\n      \"command\": \"specrun\",\n      \"args\": [\"--specs\", \"/path/to/your/specs/folder\"]\n    }\n  }\n}\n```\n\nOtherwise:\n\n```json\n{\n  \"mcpServers\": {\n    \"specrun\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"specrun\", \"--specs\", \"/absolute/path/to/your/specs\"]\n    }\n  }\n}\n```\n\nor with specific Node version:\n\n```json\n{\n  \"mcpServers\": {\n    \"specrun\": {\n      \"command\": \"/Users/YOUR_USER_NAME/.local/bin/mcp-npx-node22\",\n      \"args\": [\"specrun@latest\", \"--specs\", \"/absolute/path/to/your/specs\"],\n      \"type\": \"stdio\"\n    }\n  }\n}\n```\n\nThe `mcp-npx-node22` script file uses nvm to run specrun with Node.js 22.14.0, ensuring compatibility regardless of the default Node version on your system.:\n\n```bash\n#!/bin/bash\n# Set the PATH to include NVM's Node.js v22.14.0 installation\nexport PATH=\"/Users/YOUR_USER_NAME/.nvm/versions/node/v22.14.0/bin:$PATH\"\n\n# Execute npx with all passed arguments\nexec npx \"$@\"\n```\n\n## 💻 CLI Usage\n\n### 🚀 Start the server\n\n```bash\n# Default: stdio transport, current directory\nspecrun\n\n# Custom specs folder\nspecrun --specs ~/specs\n\n# HTTP transport mode\nspecrun --transport httpStream --port 8080\n```\n\n### Run with Node 22 using npx\n\nIf your default `node` is older than 22, run SpecRun with Node 22 directly:\n\n- `npx -y node@22 ...` runs the Node.js runtime, so the next argument must be a script path (for example `./node_modules/.bin/specrun`).\n- `specrun@latest` is an npm package spec and works directly with `npx` only when your current Node version already satisfies SpecRun requirements.\n\n```bash\n\n# Or list tools\nnpx -y node@22 ./node_modules/.bin/specrun list --specs ~/specs\n\n# If your default Node is already 22+, this also works\nnpx -y specrun@latest --specs ~/specs\n```\n\n### 📋 List loaded specs and tools\n\n```bash\n# List all loaded specifications and their tools\nspecrun list\n\n# List specs from custom folder\nspecrun list --specs ~/specs\n\n```\n\n## 🔑 Authentication Patterns\n\nThe server automatically detects authentication from environment variables using these patterns:\n\n| Pattern                                       | Auth Type       | Usage                           |\n| --------------------------------------------- | --------------- | ------------------------------- |\n| `{API_NAME}_API_KEY`                          | 🗝️ API Key      | `X-API-Key` header              |\n| `{API_NAME}_TOKEN`                            | 🎫 Bearer Token | `Authorization: Bearer {token}` |\n| `{API_NAME}_BEARER_TOKEN`                     | 🎫 Bearer Token | `Authorization: Bearer {token}` |\n| `{API_NAME}_USERNAME` + `{API_NAME}_PASSWORD` | 👤 Basic Auth   | `Authorization: Basic {base64}` |\n\nSpecRun also creates `.env` placeholders for:\n\n| Pattern                   | Purpose                      |\n| ------------------------- | ---------------------------- |\n| `{API_NAME}_SERVER_URL`   | Base URL for the API         |\n| `{API_NAME}_BEARER_TOKEN` | Token placeholder if missing |\n\nIf `{API_NAME}_SERVER_URL` is set, SpecRun writes that value into the spec before generating tools:\n\n- OpenAPI 3.0: writes the first `servers` entry.\n- OpenAPI 2.0 (formerly Swagger 2.0): writes `host`, `schemes`, and `basePath`.\n\nUpdates to `.env` are applied automatically without restarting the MCP server.\n\nThe `{API_NAME}` is derived from the filename of your OpenAPI spec:\n\n- `cars.json` → `CARS_API_KEY`\n- `github-api.yaml` → `GITHUB_TOKEN`\n- `my_custom_api.yml` → `MY_CUSTOM_API_KEY`\n\n## 🏷️ Tool Naming\n\nTools are automatically named using this pattern:\n\n- **With operationId**: `{operation_id}`\n- **Without operationId**: `{method}_{path_segments}`\n\nName normalization rules:\n\n- Converted to `snake_case`\n- Lowercased\n- Non-alphanumeric characters normalized to `_`\n- Truncated at the end when longer than 52 characters. (For VS Code/Copilot compatibility, stays within the practical 64-char internal limit.)\n- Adds short suffixes only when needed to resolve collisions\n\nSpecs:\n\n- `get_car_by_id` (from operationId)\n- `get_user_repos` (generated from `GET /user/repos`)\n\nUse the shared batch tool to run any tool with an array of inputs:\n\n```json\n{\n  \"toolName\": \"cars_getCarById\",\n  \"items\": [{ \"id\": \"123\" }, { \"id\": \"456\" }],\n  \"failFast\": false\n}\n```\n\nBatch responses return a consolidated JSON resource with per-item outputs.\n\nFor batches over 200 items, SpecRun requires explicit confirmation. This is to prevent accidental large runs that could cause performance issues or unintended consequences. The server will return a message asking for confirmation, and you can retry with `confirmLargeBatch: true` and the provided `confirmLargeBatchToken` to proceed.\n\n## 📦 Resource Outputs\n\nTool responses are returned as MCP resources with `application/json` content. Each resource includes:\n\n1. Request URL\n2. Request body\n3. Response status and body\n\nExample resource payload:\n\n```json\n{\n  \"requestUrl\": \"https://api.example.com/v1/users/123\",\n  \"requestBody\": null,\n  \"response\": {\n    \"status\": 200,\n    \"body\": {\n      \"id\": \"123\",\n      \"name\": \"Jane Doe\"\n    }\n  }\n}\n```\n\nBatch runs return a single consolidated resource containing all item results.\n\n## 📁 File Structure\n\n```\nyour-project/\n── specs/           # Your OpenAPI specs folder\n   ├── .env            # Authentication credentials\n   └── custom-api.yml  # Your OpenAPI spec files\n```\n\n## 🧭 MCP Prompts\n\nSpecRun exposes MCP prompts for common workflows:\n\nDetailed prompt guide with examples: [PROMPTS_README.md](PROMPTS_README.md)\n\n- `list_apis`: List loaded APIs/tools and ask the user to choose an endpoint\n- `generate_api_call`: Generate a ready-to-run JSON input payload for a tool\n- `explain_api_schema`: Explain parameters and request body schema with examples\n- `generate_random_data`: Generate random ready-to-run JSON payload samples for a tool\n\n## 📄 Example OpenAPI Spec\n\nHere's a minimal example that creates two tools:\n\n```yaml\n# ~/specs/example.yaml\nopenapi: 3.0.0\ninfo:\n  title: Example API\n  version: 1.0.0\nservers:\n  - url: https://api-server.placeholder\npaths:\n  /users/{id}:\n    get:\n      operationId: getUser\n      summary: Get user by ID\n      parameters:\n        - name: id\n          in: path\n          required: true\n          schema:\n            type: string\n      responses:\n        \"200\":\n          description: User found\n  /users:\n    post:\n      operationId: createUser\n      summary: Create a new user\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              type: object\n              properties:\n                name:\n                  type: string\n                email:\n                  type: string\n      responses:\n        \"201\":\n          description: User created\n```\n\nThis creates tools named:\n\n- `example_getUser`\n- `example_createUser`\n\n## 🔧 Troubleshooting\n\n### ❌ No tools appearing?\n\n1. Check that your OpenAPI specs are valid:\n\n   ```bash\n   specrun list --specs /path/to/specs\n   ```\n\n2. Ensure files have correct extensions (`.json`, `.yaml`, `.yml`)\n\n3. Check the server logs for parsing errors\n\n> **⚠️ Note:** SpecRun works best when you use absolute paths (with no spaces) for the `--specs` argument and other file paths. Relative paths or paths containing spaces may cause issues on some platforms or with some MCP clients.\n\n### 🔐 Authentication not working?\n\n1. Verify your `.env` file is in the specs directory\n2. Check the naming pattern matches your spec filename\n3. Use the list command to verify auth configuration:\n   ```bash\n   specrun list\n   ```\n\n### 🔄 Tools not updating after spec changes?\n\n1. Restart the MCP server to reload the specs\n2. Check file permissions\n3. Restart the MCP client if needed\n\n## 🛠️ Development\n\n```bash\n# Clone and install\ngit clone git@github.com:Pavel-Piha/specrun.git\ncd specrun\nnpm install\n\n# Build\nnpm run build\n\nnpm run dev -- list --specs ./specs\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n",
  "bytes": 11225,
  "sha": "ddd62f1203610caf5cf0235ee7449f6139d20b76b4afb39a4e39c4646a178a35",
  "repo_slug": "pavelpiha/specrun",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pavelpiha_specrun_161548b3/readme"
}