Open API & Agent / Client Integration Guide

Direct HTTP / REST API recommended · zero install

Evidence / RAG search:

POST https://xiangshang.ngrok.app/api/evidence/search
Content-Type: application/json

{
  "query":  "robot obstacle avoidance algorithms",
  "top_k":  5,
  "mode":   "hybrid",
  "rerank": true
}

Solution consult (slow — set request timeout ≥ 180s):

curl -X POST "https://xiangshang.ngrok.app/api/consult" \
  -H "Content-Type: application/json" --max-time 180 \
  -d '{"question":"how to build a robot obstacle avoidance system","top_k":30,"rerank":true}'

ChatGPT — Custom GPTs / Actions

OpenAPI Schema URL:

https://xiangshang.ngrok.app/openapi.json

Setup: in the Custom GPT editor → Configure → Actions → click Import from URL, paste the link above, set Authentication to None.

WorkBuddy integration

Option A (recommended · OpenAPI import): WorkBuddy settings → Custom Tools / Plugin → "Import from OpenAPI URL", enter https://xiangshang.ngrok.app/openapi.json. This auto-registers the Consult, Lookup, Evidence and Search tools.

Option B (MCP mode): download the MCP server and register it as a local MCP command. The consult tool already uses a 180s internal timeout.

pip install mcp
curl -o ontology_mcp_server.py https://xiangshang.ngrok.app/mcp/ontology_mcp_server.py

{
  "mcpServers": {
    "entropy-box": {
      "command": "python",
      "args": ["/absolute/path/to/ontology_mcp_server.py"],
      "env": { "ONTOLOGY_API_BASE": "https://xiangshang.ngrok.app" }
    }
  }
}

Trae / Cursor / Claude Desktop — MCP protocol

Trae, Cursor and Claude Desktop all support MCP servers natively. Step 1 — download the all-in-one MCP script:

pip install mcp
curl -o ontology_mcp_server.py https://xiangshang.ngrok.app/mcp/ontology_mcp_server.py

Step 2 — add to the MCP config file (Trae: Settings → MCP Servers; Claude: claude_desktop_config.json):

{
  "mcpServers": {
    "entropy-box": {
      "command": "python",
      "args": ["/absolute/path/to/ontology_mcp_server.py"],
      "env": { "ONTOLOGY_API_BASE": "https://xiangshang.ngrok.app" }
    }
  }
}

Language support — 中文 / English

The API auto-detects the query language. Chinese queries (e.g. “双足机器人上楼梯的步态规划”) and English queries (e.g. “robot obstacle avoidance algorithms”) are passed through directly and return equally relevant results. No translation flag is required — just send the query in either language.

About RAG evidence

The Evidence endpoint (POST /api/evidence/search) is a RAG over the curated evidence knowledge base — it retrieves de-identified fragments of engineering patterns, open-source selection rationale, algorithm-comparison notes and benchmark data (documented in the OpenAPI spec as “调研证据与开源选型依据检索 / Evidence Search”). It is ideal for questions like “why X is not used over Y” or “known defects of library Z in real deployment”.