Skip to content

Commit d13543e

Browse files
kadykovkadykov
committed
docs(claude-code): add usage guide for Claude Code integration
Add comprehensive guide for integrating MCP OpenAPI Schema Explorer with Claude Code, including installation methods, configuration, and usage examples. Update README and llms-install.md to reference the new guide.
1 parent 11e3beb commit d13543e

File tree

3 files changed

+284
-0
lines changed

3 files changed

+284
-0
lines changed

‎CLAUDE_CODE.md‎

Lines changed: 277 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,277 @@
1+
# Using MCP OpenAPI Schema Explorer with Claude Code
2+
3+
This guide provides step-by-step instructions for using the MCP OpenAPI Schema Explorer with [Claude Code](https://docs.anthropic.com/en/docs/build-with-claude/claude-code), Anthropic's CLI tool for coding with Claude.
4+
5+
## What is Claude Code?
6+
7+
Claude Code is a command-line tool that lets you interact with Claude directly from your terminal. It supports MCP (Model Context Protocol) servers, allowing Claude to access external tools and data sources like OpenAPI specifications.
8+
9+
## Prerequisites
10+
11+
1. **Install Claude Code CLI**: Follow the [official installation instructions](https://docs.anthropic.com/en/docs/build-with-claude/claude-code)
12+
2. **Verify installation**: Run `claude --version` in your terminal
13+
14+
## Adding the MCP Server to Claude Code
15+
16+
Claude Code provides a convenient CLI command to add MCP servers: `claude mcp add`
17+
18+
### Method 1: Using npx (Recommended)
19+
20+
This method automatically downloads and runs the latest version without requiring installation:
21+
22+
```bash
23+
# For a remote API specification
24+
claude mcp add my-api -- npx -y mcp-openapi-schema-explorer@latest https://petstore3.swagger.io/api/v3/openapi.json
25+
26+
# For a local API specification (use absolute path)
27+
claude mcp add my-api -- npx -y mcp-openapi-schema-explorer@latest /path/to/your/openapi.json
28+
29+
# With custom output format (yaml)
30+
claude mcp add my-api -- npx -y mcp-openapi-schema-explorer@latest https://api.example.com/openapi.json --output-format yaml
31+
```
32+
33+
### Method 2: Using Node.js (Local Development)
34+
35+
If you're developing or testing a local version:
36+
37+
```bash
38+
# First, build the project
39+
cd /path/to/mcp-openapi-schema-explorer
40+
npm install
41+
npm run build
42+
43+
# Then add to Claude Code
44+
claude mcp add my-api -- node /path/to/mcp-openapi-schema-explorer/dist/src/index.js /path/to/spec.json
45+
```
46+
47+
### Method 3: Using Docker
48+
49+
For containerized deployments:
50+
51+
```bash
52+
# For remote URL
53+
claude mcp add my-api -- docker run --rm -i kadykov/mcp-openapi-schema-explorer:latest https://petstore3.swagger.io/api/v3/openapi.json
54+
55+
# For local file (requires volume mounting)
56+
claude mcp add my-api -- docker run --rm -i -v /full/host/path/to/spec.yaml:/spec/api.yaml kadykov/mcp-openapi-schema-explorer:latest /spec/api.yaml
57+
```
58+
59+
## Managing MCP Servers
60+
61+
### List configured servers
62+
63+
```bash
64+
claude mcp list
65+
```
66+
67+
This command shows all configured MCP servers and their connection status.
68+
69+
### Get server details
70+
71+
```bash
72+
claude mcp get my-api
73+
```
74+
75+
### Remove a server
76+
77+
```bash
78+
claude mcp remove my-api
79+
```
80+
81+
## Using the MCP Server with Claude Code
82+
83+
Once the MCP server is configured, you can interact with it in your Claude Code sessions:
84+
85+
### Interactive Mode
86+
87+
```bash
88+
claude
89+
```
90+
91+
Then ask Claude questions like:
92+
93+
- "Using the my-api MCP server, list all available API endpoints"
94+
- "Show me the details of the GET /users endpoint from the my-api server"
95+
- "What are all the component schemas available in the my-api server?"
96+
- "Show me the User schema definition"
97+
98+
### Print Mode (Non-interactive)
99+
100+
Use the `-p` or `--print` flag for single-query responses:
101+
102+
```bash
103+
claude -p "Using the my-api MCP server, list all available endpoints"
104+
```
105+
106+
This is useful for scripting or quick queries.
107+
108+
## Resource Templates
109+
110+
The MCP OpenAPI Schema Explorer uses **resource templates** to provide structured access to different parts of the OpenAPI specification. Here are the available templates:
111+
112+
### Top-Level Fields
113+
114+
- **URI**: `openapi://{field}`
115+
- **Examples**: `openapi://info`, `openapi://servers`, `openapi://paths`, `openapi://components`
116+
- **Usage**: "Show me the info section from the my-api server"
117+
118+
### List Path Methods
119+
120+
- **URI**: `openapi://paths/{path}`
121+
- **Examples**: `openapi://paths/%2Fusers` (for `/users`)
122+
- **Note**: Paths must be URL-encoded
123+
- **Usage**: "List all HTTP methods available for the /users path"
124+
125+
### Get Operation Details
126+
127+
- **URI**: `openapi://paths/{path}/{method}`
128+
- **Examples**: `openapi://paths/%2Fusers/get`, `openapi://paths/%2Fusers/get,post`
129+
- **Usage**: "Show me the details of the GET /users endpoint"
130+
131+
### List Component Names
132+
133+
- **URI**: `openapi://components/{type}`
134+
- **Examples**: `openapi://components/schemas`, `openapi://components/responses`
135+
- **Usage**: "List all available schemas"
136+
137+
### Get Component Details
138+
139+
- **URI**: `openapi://components/{type}/{name}`
140+
- **Examples**: `openapi://components/schemas/User`, `openapi://components/schemas/User,Order`
141+
- **Usage**: "Show me the User schema"
142+
143+
## Configuration File
144+
145+
Claude Code stores MCP server configurations in `~/.claude.json` under the `projects` section. Here's an example of what it looks like:
146+
147+
```json
148+
{
149+
"projects": {
150+
"/path/to/your/project": {
151+
"mcpServers": {
152+
"my-api": {
153+
"type": "stdio",
154+
"command": "npx",
155+
"args": [
156+
"-y",
157+
"mcp-openapi-schema-explorer@latest",
158+
"https://petstore3.swagger.io/api/v3/openapi.json",
159+
"--output-format",
160+
"yaml"
161+
],
162+
"env": {}
163+
}
164+
}
165+
}
166+
}
167+
}
168+
```
169+
170+
## Tips and Best Practices
171+
172+
1. **Use descriptive names**: When adding servers, use names that clearly identify the API (e.g., `petstore-api`, `stripe-api`)
173+
174+
2. **Multiple APIs**: You can add multiple MCP servers for different APIs:
175+
176+
```bash
177+
claude mcp add petstore -- npx -y mcp-openapi-schema-explorer@latest https://petstore3.swagger.io/api/v3/openapi.json
178+
claude mcp add stripe -- npx -y mcp-openapi-schema-explorer@latest https://api.stripe.com/v1/openapi.json
179+
```
180+
181+
3. **Output formats**: Choose the format that works best for your use case:
182+
- `--output-format json` (default): Standard JSON formatting
183+
- `--output-format yaml`: YAML formatting (more human-readable)
184+
- `--output-format json-minified`: Minified JSON (saves tokens)
185+
186+
4. **URL encoding**: When constructing URIs manually, remember to URL-encode paths:
187+
- `/users/{id}` becomes `%2Fusers%2F%7Bid%7D`
188+
- You typically don't need to do this manually when asking Claude in natural language
189+
190+
5. **Check connection status**: Run `claude mcp list` periodically to ensure your servers are connected
191+
192+
## Troubleshooting
193+
194+
### Server not connecting
195+
196+
If `claude mcp list` shows a server as not connected:
197+
198+
1. Verify the command works standalone:
199+
200+
```bash
201+
npx -y mcp-openapi-schema-explorer@latest https://petstore3.swagger.io/api/v3/openapi.json
202+
```
203+
204+
2. Check the specification URL or file path is valid
205+
206+
3. Remove and re-add the server:
207+
```bash
208+
claude mcp remove my-api
209+
claude mcp add my-api -- npx -y mcp-openapi-schema-explorer@latest <your-spec-url>
210+
```
211+
212+
### Permission issues
213+
214+
If you encounter permission errors, ensure:
215+
216+
- File paths are absolute (not relative)
217+
- You have read access to local specification files
218+
- Remote URLs are accessible from your network
219+
220+
### Debug mode
221+
222+
Enable debug mode to see detailed MCP communication:
223+
224+
```bash
225+
claude -d "Using the my-api server, list all endpoints"
226+
```
227+
228+
## Examples
229+
230+
### Example 1: Exploring the Petstore API
231+
232+
```bash
233+
# Add the Petstore API
234+
claude mcp add petstore -- npx -y mcp-openapi-schema-explorer@latest https://petstore3.swagger.io/api/v3/openapi.json
235+
236+
# Query it
237+
claude -p "Using the petstore server, what are all the pet-related endpoints?"
238+
```
239+
240+
### Example 2: Working with a local API spec
241+
242+
```bash
243+
# Add your local API
244+
claude mcp add my-service -- npx -y mcp-openapi-schema-explorer@latest /home/user/projects/my-api/openapi.yaml --output-format yaml
245+
246+
# Interactive exploration
247+
claude
248+
# Then ask: "Using the my-service server, show me all available endpoints and their operations"
249+
```
250+
251+
### Example 3: Multiple APIs
252+
253+
```bash
254+
# Add multiple APIs
255+
claude mcp add github -- npx -y mcp-openapi-schema-explorer@latest https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
256+
claude mcp add gitlab -- npx -y mcp-openapi-schema-explorer@latest https://gitlab.com/api/v4/openapi.json
257+
258+
# Compare them
259+
claude -p "Compare the authentication methods used by the github and gitlab MCP servers"
260+
```
261+
262+
## Further Resources
263+
264+
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/build-with-claude/claude-code)
265+
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
266+
- [MCP OpenAPI Schema Explorer Repository](https://github.com/kadykov/mcp-openapi-schema-explorer)
267+
268+
## Feedback
269+
270+
If you encounter issues specific to Claude Code integration, please:
271+
272+
1. Check the [GitHub Issues](https://github.com/kadykov/mcp-openapi-schema-explorer/issues)
273+
2. Open a new issue with:
274+
- Claude Code version (`claude --version`)
275+
- Your MCP server configuration
276+
- Error messages or unexpected behavior
277+
- Steps to reproduce

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,11 @@ While other MCP servers exist that provide access to OpenAPI specs via _Tools_,
3838

3939
For more details on MCP clients and their capabilities, see the [MCP Client Documentation](https://modelcontextprotocol.io/clients).
4040

41+
## Quick Start Guides by Client
42+
43+
- **[Claude Code](CLAUDE_CODE.md)** - Anthropic's CLI tool for coding with Claude
44+
- **Claude Desktop, Cline, Windsurf** - See installation instructions below
45+
4146
## Installation
4247

4348
For the recommended usage methods (`npx` and Docker, described below), **no separate installation step is required**. Your MCP client will download the package or pull the Docker image automatically based on the configuration you provide.

‎llms-install.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
This guide explains how to add the MCP OpenAPI Schema Explorer server to your MCP client (e.g., Claude Desktop, Windsurf, Cline). This involves adding a configuration entry to your client's settings file that tells the client how to run the server process. The server itself doesn't require separate configuration beyond the command-line arguments specified in the client settings.
44

5+
> **Note:** For Claude Code users, see the dedicated [Claude Code guide](CLAUDE_CODE.md) which includes CLI-specific instructions.
6+
57
> **Important Note:** This server provides **resource templates**, not pre-enumerated resources. Your MCP client will discover available URI templates through `resources/templates/list` and then construct specific URIs to access content. If you check `resources/list` (without "templates"), it will return an empty list—this is expected behavior. See the [MCP Resource Templates documentation](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#resource-templates) for more details.
68
79
## Prerequisites

0 commit comments

Comments
 (0)