Skip to main content

CLI

The package exposes the graph-tool-call command. Use it to prototype a tool catalog locally, generate collection artifacts for an adapter, run readiness checks, or serve a filtered MCP tool surface.

graph-tool-call --version
graph-tool-call --help

Command Overview​

CommandUse It For
searchOne-shot ingest plus retrieval from an OpenAPI source or graph file
ingestBuild and save a reusable ToolGraph JSON file
retrieveSearch an already-built graph
inspect-openapiRun deterministic OpenAPI readiness diagnostics
build-openapi-collectionBuild a storage-ready collection artifact
analyzeInspect graph structure, duplicates, conflicts, or orphan tools
visualizeExport HTML, GraphML, or Cypher graph views
infoPrint node and edge summaries
dashboardLaunch the local interactive dashboard
callSearch and execute an OpenAPI tool through the built-in HTTP executor
serveRun graph-tool-call as an MCP server
proxyAggregate and filter multiple MCP backends

Search Without A Build Step​

Use search when you are exploring a spec and do not need a persisted artifact.

graph-tool-call search "find pets by status" \
  --source https://petstore3.swagger.io/api/v3/openapi.json \
  --top-k 8 \
  --scores

Return JSON for scripts or test fixtures:

graph-tool-call search "find pets by status" \
  --source ./openapi.json \
  --top-k 8 \
  --scores \
  --json

Use --cache graph.json for repeated local searches against the same source.

Build And Retrieve​

Use this workflow when the graph should be reused by a service, benchmark, or manual inspection step.

graph-tool-call ingest ./openapi.json -o graph.json
graph-tool-call retrieve "cancel an order" --graph graph.json --top-k 8
graph-tool-call analyze graph.json --duplicates --orphans

Useful ingest flags:

FlagPurpose
--required-onlyKeep only required OpenAPI parameters during ingest
--include-deprecatedInclude deprecated operations
--embedding [MODEL]Build an optional embedding index
--organizeRun automatic graph organization
--llm PROVIDER/MODELUse an LLM provider for ontology enrichment
--allow-private-hostsPermit trusted private/internal URL loading
--forceRebuild even when cache exists

Inspect OpenAPI Readiness​

Run this before enabling plan or execute flows for a collection.

graph-tool-call inspect-openapi ./openapi.json
graph-tool-call inspect-openapi ./openapi.json --json

Classify product-specific field names without hard-coding them into the engine:

graph-tool-call inspect-openapi ./openapi.json \
  --context-field mallNo,siteNo \
  --paging-field page,size \
  --search-filter-field keyword,searchType

The report includes readiness score, issue codes, schema coverage, semantic coverage, graph connectivity, and recommendations.

Build A Collection Artifact​

Use build-openapi-collection when a product adapter needs a single JSON payload containing tools, graph, readiness, semantic summary, edge quality, and source snapshot metadata.

graph-tool-call build-openapi-collection ./openapi.json \
  -o collection.json \
  --context-field mallNo,siteNo \
  --paging-field page,size \
  --auth-field Authorization,X-API-Key

Alias options are generic alias=canonical mappings:

graph-tool-call build-openapi-collection ./openapi.json \
  --resource-alias goods=product,item=product \
  --action-alias 조회=read,등록=create \
  --module-alias memberMgmt=member

Write to stdout for pipelines:

graph-tool-call build-openapi-collection ./openapi.json -o - | jq '.semantic_summary'

Execute A Tool​

call is useful for local smoke tests. Production adapters usually provide their own executor so they can control auth, tenancy, retries, auditing, and mutation safety.

graph-tool-call call "find pet by id" \
  --source ./openapi.json \
  --base-url https://petstore3.swagger.io/api/v3 \
  --args '{"petId": 1}' \
  --dry-run

Run without --dry-run only against trusted APIs:

graph-tool-call call "find pet by id" \
  --source ./openapi.json \
  --base-url https://petstore3.swagger.io/api/v3 \
  --args '{"petId": 1}'

Serve Or Proxy MCP​

Expose a graph as an MCP server:

graph-tool-call serve \
  --source ./openapi.json \
  --transport stdio

Serve over HTTP transport when the client supports it:

graph-tool-call serve \
  --graph graph.json \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000

Aggregate multiple MCP backends:

graph-tool-call proxy \
  --config .mcp.json \
  --top-k 10 \
  --passthrough-threshold 30

Visualize​

graph-tool-call visualize graph.json -o graph.html
graph-tool-call visualize graph.json --format graphml -o graph.graphml
graph-tool-call visualize graph.json --format cypher -o graph.cypher

Use visualizations for local inspection. Large product UIs should usually render clustered summaries or filtered subgraphs instead of drawing every edge at once.

Exit-Code Guidance​

The CLI uses non-zero exits for unrecoverable command errors such as invalid JSON arguments, missing graph files, unsupported aliases, or no selected tool in call. For validation pipelines, prefer --json output and assert on report fields instead of parsing human-readable text.