{"_id":"@awssam/mcp-swagger","_rev":"2-df4fa242c68f4a3701e7eb5082b85052","name":"@awssam/mcp-swagger","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@awssam/mcp-swagger","version":"1.0.0","keywords":["mcp","swagger","openapi","model-context-protocol","ai","claude","api-documentation","rest-api","api-tools"],"author":{"name":"NextShow"},"license":"MIT","_id":"@awssam/mcp-swagger@1.0.0","maintainers":[{"name":"awtsoft","email":"awtsoft@gmail.com"}],"homepage":"https://github.com/awssam/mcp-swagger#readme","bugs":{"url":"https://github.com/awssam/mcp-swagger/issues"},"bin":{"mcp-swagger":"src/index.js"},"dist":{"shasum":"349d49f6060b11c59b6bbfb1c1da59c69c0f4c74","tarball":"https://registry.npmjs.org/@awssam/mcp-swagger/-/mcp-swagger-1.0.0.tgz","fileCount":9,"integrity":"sha512-kgRCIji9UxoWHCMrTDJIr2BxY16BR6PVeIJVcd6Gz2emD9qP8D5kIv0D2N5UUxikFXdGlv8mYr5zD2iOWebYFg==","signatures":[{"sig":"MEUCIDbAb1lkceiyEW6MF+TY5hmFpz0hxrfc/YmKx/+Tfy2JAiEA8nyQx21+W7aSHVOAtGkLxhMs9+HLh7Z92Z/NF26hNnM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37130},"main":"src/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"aa71fb16dfbee9543ef385b6d7f128a3e9035365","scripts":{"test":"echo \"Error: no test specified\" && exit 1","start":"node src/index.js"},"_npmUser":{"name":"awtsoft","email":"awtsoft@gmail.com"},"repository":{"url":"git+https://github.com/awssam/mcp-swagger.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for exposing Swagger/OpenAPI documentation to AI models like Claude","directories":{},"_nodeVersion":"22.19.0","dependencies":{"@modelcontextprotocol/sdk":"^1.18.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp-swagger_1.0.0_1759188565084_0.15823897215518068","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@awssam/mcp-swagger","version":"1.0.1","description":"MCP server for exposing Swagger/OpenAPI documentation to AI models like Claude","type":"module","main":"src/index.js","bin":{"mcp-swagger":"src/index.js"},"scripts":{"start":"node src/index.js","test":"echo \"Error: no test specified\" && exit 1"},"keywords":["mcp","swagger","openapi","model-context-protocol","ai","claude","api-documentation","rest-api","api-tools"],"author":{"name":"NextShow"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/awssam/mcp-swagger.git"},"bugs":{"url":"https://github.com/awssam/mcp-swagger/issues"},"homepage":"https://github.com/awssam/mcp-swagger#readme","publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.18.2"},"engines":{"node":">=18.0.0"},"_id":"@awssam/mcp-swagger@1.0.1","gitHead":"784d82dc4f21532bef4577906540095df15dd637","_nodeVersion":"22.19.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-Vw19Ix7QSsI0BeuNM5OOQcgvIoYWk6EpJAJv4PhfXkcHFeJxwJ3nUCVwvxZ+MyyOMkj0f3L+E5f8d7efxAkRSw==","shasum":"12a5459cfccfd0aa66b367a47cedfd20b5fac14d","tarball":"https://registry.npmjs.org/@awssam/mcp-swagger/-/mcp-swagger-1.0.1.tgz","fileCount":9,"unpackedSize":36997,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDx8nZ4nz1NKj4W3JpfnDbox5U58XXUQzl+5nzwFAlOlgIhAIQDLRM8SCpOSWfFk2CUxkfNpRwHYN3zP4H6hbsf+Q6R"}]},"_npmUser":{"name":"awtsoft","email":"awtsoft@gmail.com"},"directories":{},"maintainers":[{"name":"awtsoft","email":"awtsoft@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-swagger_1.0.1_1759189272695_0.47589134661207066"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-29T23:29:25.017Z","modified":"2025-09-29T23:41:13.090Z","1.0.0":"2025-09-29T23:29:25.281Z","1.0.1":"2025-09-29T23:41:12.905Z"},"bugs":{"url":"https://github.com/awssam/mcp-swagger/issues"},"author":{"name":"NextShow"},"license":"MIT","homepage":"https://github.com/awssam/mcp-swagger#readme","keywords":["mcp","swagger","openapi","model-context-protocol","ai","claude","api-documentation","rest-api","api-tools"],"repository":{"type":"git","url":"git+https://github.com/awssam/mcp-swagger.git"},"description":"MCP server for exposing Swagger/OpenAPI documentation to AI models like Claude","maintainers":[{"name":"awtsoft","email":"awtsoft@gmail.com"}],"readme":"# @awssam/mcp-swagger\n\nMCP (Model Context Protocol) server for exposing Swagger/OpenAPI documentation to AI models like Claude. This tool allows AI assistants to explore, understand, and interact with your API documentation seamlessly.\n\n## Features\n\n- **14 Powerful Tools** for exploring API documentation\n- **Automatic Caching** for fast responses\n- **OpenAPI 3.0 Support** (Swagger 2.0 compatible)\n- **Token-Optimized** responses for efficient AI interactions\n- **Search & Discovery** with intelligent scoring\n- **Path Validation** with typo suggestions\n- **Curl Generation** with example payloads\n- **Schema Analysis** and reference tracking\n\n## Installation\n\n```bash\nnpm install -g @awssam/mcp-swagger\n```\n\n## Quick Start\n\n### Using with Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"swagger\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@awssam/mcp-swagger\",\n        \"https://petstore.swagger.io/v2/swagger.json\"\n      ]\n    }\n  }\n}\n```\n\n### Using with Claude CLI (Claude Code)\n\n**Option 1: Using `claude mcp add` command (Recommended)**\n\n```bash\nclaude mcp add swagger npx @awssam/mcp-swagger https://petstore.swagger.io/v2/swagger.json\n```\n\n**Option 2: Manual Configuration**\n\nAdd to your Claude CLI configuration file:\n\n**Location**: `~/.config/claude/config.yaml`\n\n```yaml\nmcpServers:\n  swagger:\n    command: npx\n    args:\n      - \"@awssam/mcp-swagger\"\n      - \"https://petstore.swagger.io/v2/swagger.json\"\n```\n\nOr if installed globally:\n\n```yaml\nmcpServers:\n  swagger:\n    command: mcp-swagger\n    args:\n      - \"https://petstore.swagger.io/v2/swagger.json\"\n```\n\nAfter adding the configuration, restart Claude CLI for the changes to take effect.\n\n### Using with Environment Variable\n\n```bash\nexport API_URL=https://your-api.com/api-docs\nnpx @awssam/mcp-swagger\n```\n\n### Using as CLI\n\n```bash\nnpx @awssam/mcp-swagger https://your-api.com/api-docs\n```\n\n## Available Tools\n\n### 1. `listEndpoints`\nLists all available API endpoints with their HTTP methods and tags.\n\n**Parameters:**\n- `tag` (optional): Filter by specific tag\n\n**Example:**\n```json\n{\n  \"tag\": \"users\"\n}\n```\n\n### 2. `getEndpointDetails`\nRetrieves complete details of a specific endpoint including parameters, request body, responses, and schemas.\n\n**Parameters:**\n- `path` (required): Endpoint path (e.g., `/users/{id}`)\n- `method` (optional): HTTP method (get, post, put, delete, patch)\n\n**Example:**\n```json\n{\n  \"path\": \"/users/{id}\",\n  \"method\": \"get\"\n}\n```\n\n### 3. `searchEndpoints`\nSearches for endpoints by keyword in paths, descriptions, and tags. Results are sorted by relevance.\n\n**Parameters:**\n- `query` (required): Search term\n\n**Example:**\n```json\n{\n  \"query\": \"authentication\"\n}\n```\n\n### 4. `getSchemas`\nRetrieves data schemas (DTOs) defined in the API. Without parameters, lists all available schemas.\n\n**Parameters:**\n- `schemaName` (optional): Specific schema name to retrieve\n\n**Example:**\n```json\n{\n  \"schemaName\": \"User\"\n}\n```\n\n### 5. `listTags`\nLists all tags used to categorize endpoints in the API.\n\n### 6. `getEndpointsByTag`\nRetrieves all endpoints associated with a specific tag.\n\n**Parameters:**\n- `tag` (required): Tag name\n\n**Example:**\n```json\n{\n  \"tag\": \"authentication\"\n}\n```\n\n### 7. `getApiInfo`\nRetrieves API metadata including title, version, description, servers, contact info, and license.\n\n### 8. `getSecuritySchemes`\nLists authentication/authorization schemes available (OAuth2, API keys, Bearer tokens, etc.).\n\n### 9. `getServerUrls`\nRetrieves available server URLs and their environments (dev, staging, prod, etc.).\n\n### 10. `validateEndpointPath`\nChecks if an endpoint path exists. If not found, suggests similar paths to help with typos.\n\n**Parameters:**\n- `path` (required): Endpoint path to validate\n\n**Example:**\n```json\n{\n  \"path\": \"/users/{id}\"\n}\n```\n\n### 11. `getSchemaReferences`\nFinds all endpoints that use a specific schema. Useful for impact analysis when modifying schemas.\n\n**Parameters:**\n- `schemaName` (required): Schema name to search for\n\n**Example:**\n```json\n{\n  \"schemaName\": \"User\"\n}\n```\n\n### 12. `generateCurlExample`\nGenerates a curl command example for a specific endpoint, including headers and sample request body.\n\n**Parameters:**\n- `path` (required): Endpoint path\n- `method` (required): HTTP method\n\n**Example:**\n```json\n{\n  \"path\": \"/users\",\n  \"method\": \"post\"\n}\n```\n\n### 13. `getDeprecatedEndpoints`\nLists all endpoints marked as deprecated. Useful for migration planning.\n\n### 14. `executeEndpoint`\n**✨ NEW** - Executes an API endpoint and returns the actual response. Automatically uses required headers from the Swagger spec. Perfect for testing endpoints and fetching real-time data.\n\n**Parameters:**\n- `path` (required): Endpoint path (e.g., `/users/{id}`)\n- `method` (required): HTTP method (get, post, put, delete, patch)\n- `baseUrl` (optional): Base server URL (uses Swagger default if not provided)\n- `pathParams` (optional): Path parameters object (e.g., `{\"id\": \"123\"}`)\n- `queryParams` (optional): Query parameters object (e.g., `{\"page\": 1, \"perPage\": 10}`)\n- `headers` (optional): Custom headers object (e.g., `{\"Authorization\": \"Bearer token\"}`)\n- `body` (optional): Request body for POST/PUT/PATCH\n\n**Example:**\n```json\n{\n  \"path\": \"/admin/organizations\",\n  \"method\": \"get\",\n  \"baseUrl\": \"http://localhost:4000\",\n  \"queryParams\": {\n    \"page\": 1,\n    \"perPage\": 10\n  },\n  \"headers\": {\n    \"x-dev-code\": \"ILoveMom\"\n  }\n}\n```\n\n**Response includes:**\n- `success`: Boolean indicating if request succeeded\n- `status`: HTTP status code\n- `statusText`: HTTP status message\n- `data`: Response body (parsed JSON or text)\n- `headers`: Response headers\n- `url`: Full URL that was called\n- `method`: HTTP method used\n\n## Project Structure\n\n```\nsrc/\n├── index.js                 # Entry point & server setup\n├── config.js               # Configuration management\n├── swagger/\n│   ├── fetcher.js          # Swagger doc fetching & caching\n│   └── parser.js           # Endpoint, schema, and tag parsing\n└── tools/\n    ├── definitions.js      # Tool schemas & definitions\n    └── handlers.js         # Tool request handlers\n```\n\n## Configuration\n\nThe server accepts the API URL in three ways (in order of precedence):\n\n1. **Command-line argument**: `npx @awssam/mcp-swagger <URL>`\n2. **Environment variable**: `export API_URL=<URL>`\n3. **Default**: `http://localhost:3000/api-json`\n\n## Requirements\n\n- Node.js >= 18.0.0\n- Valid Swagger/OpenAPI JSON or YAML endpoint\n\n## Use Cases\n\n- **API Exploration**: Let AI understand and navigate your API\n- **Documentation Assistance**: Get instant answers about endpoints\n- **Code Generation**: Generate curl commands and examples\n- **Migration Planning**: Find deprecated endpoints\n- **Impact Analysis**: Track schema usage across endpoints\n- **Developer Onboarding**: Quick API discovery and learning\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/awssam/mcp-swagger.git\ncd mcp-swagger\n\n# Install dependencies\nnpm install\n\n# Run locally\nnpm start https://petstore.swagger.io/v2/swagger.json\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## Support\n\n- **Issues**: https://github.com/awssam/mcp-swagger/issues\n- **Author**: Awssam Saidi\n\n## Related Projects\n\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Anthropic Claude](https://www.anthropic.com/claude)\n- [OpenAPI Specification](https://swagger.io/specification/)","readmeFilename":"README.md"}