CLI and MCP server for querying OpenAPI/Swagger schemas - extract routes, entities, and schemas
npm install @thinknimble/tnm-clitnm-cli is a command line interface for querying and extracting information from OpenAPI schema files. It allows you to inspect schemas, routes, and entities defined in your OpenAPI specifications.
First, install bun (required):
``bash`
curl -fsSL https://bun.sh/install | bash
Then install the CLI:
`bash`
npm install -g @thinknimble/tnm-clior
bun install -g @thinknimble/tnm-cli
The CLI requires an OpenAPI schema to be provided via either a file path or a YAML/JSON string.
`bash`
tn-models-cli [--file
- --file, -f - Path to the OpenAPI schema file (YAML or JSON)--yaml, -y
- - OpenAPI schema as a YAML or JSON string
#### hello
Print a hello message.
`bash`
tn-models-cli --file schema.yaml hello
#### schema
Get a specific schema by name from the components/schemas section.
`bash`
tn-models-cli --file schema.yaml schema User
#### route
Get route information for a specific path.
`bash`
tn-models-cli --file schema.yaml route /api/users/
#### routes
Get all routes defined in the OpenAPI schema.
`bash`
tn-models-cli --file schema.yaml routes
#### entities
Get all entity schemas from the components/schemas section.
`bash`
tn-models-cli --file schema.yaml entities
Using a local file:
`bash`
tn-models-cli --file openapi.yaml routes
tn-models-cli -f openapi.json schema Pet
Using inline YAML:
`bash`
tn-models-cli --yaml "$(cat schema.yaml)" entities
To install dependencies:
`bash`
bun install
To build:
`bash`
bun run build
To run locally:
`bash`
bun run src/v1/cli.ts --file
This project was created using bun init in bun v1.1.22. Bun is a fast all-in-one JavaScript runtime.
This tool can run as an MCP (Model Context Protocol) server in two modes:
The stdio server uses the standard MCP protocol over stdio for integration with Claude Desktop and other MCP clients.
`bashUsing the built version
tn-models-mcp
Testing with MCP Inspector:
`bash
npx @modelcontextprotocol/inspector build/cli.js -m
`MCP Tools Available:
-
get_schema - Get a specific schema by name (requires schema_path and schema_name parameters)
- get_route - Get route information for a path (requires schema_path and route_path parameters)
- get_routes - Get all routes (requires schema_path parameter)
- get_entities - Get all entity schemas (requires schema_path parameter)Note: In MCP mode, the schema file path is passed as a parameter to each tool call, not at startup.
Claude Desktop / Claude Code Configuration:
Add to your MCP config (
~/.claude/settings.json for Claude Code, or claude_desktop_config.json for Claude Desktop):Using npx (recommended for npm package):
`json
{
"mcpServers": {
"tnm-openapi": {
"command": "npx",
"args": ["-y", "@thinknimble/tnm-cli", "-m"]
}
}
}
`Or using the dedicated MCP binary:
`json
{
"mcpServers": {
"tnm-openapi": {
"command": "npx",
"args": ["-y", "-p", "@thinknimble/tnm-cli", "tn-models-mcp"]
}
}
}
`Using bunx (for local development):
`json
{
"mcpServers": {
"tnm-openapi": {
"command": "bunx",
"args": ["/path/to/tnm-cli/src/v1/mcp-server.ts"]
}
}
}
`$3
You can also run an HTTP server that exposes REST endpoints. The schema can be provided either at startup or per-request.
Start with a default schema:
`bash
Using the serve subcommand
tn-models-cli --file ./sample.yaml serve --port 8080Or using the --mcp flag
tn-models-cli --mcp --file ./sample.yaml --port 8080
`Start without a default schema:
`bash
tn-models-cli serve --port 8080
Provide schema_path as a query parameter in each request
`HTTP Endpoints:
-
GET /health - Health check
- GET /routes?schema_path=/path/to/schema.yaml - Get all routes
- GET /entities?schema_path=/path/to/schema.yaml - Get all entities
- GET /schema/:name?schema_path=/path/to/schema.yaml - Get specific schema
- GET /route?path=/api/users&schema_path=/path/to/schema.yaml - Get specific routeIf a default schema was provided at startup, the
schema_path` query parameter is optional.