dsh-openapi
Give DeepSeek Harness a safe, structured doorway into any OpenAPI 3.x API.
中文说明 · DeepSeek Harness
dsh-openapi is a native DeepSeek Harness bundle that indexes configured OpenAPI documents and adds three model-facing tools:
openapi_list discovers APIs and searches operations.openapi_describe returns parameters, request bodies, servers, and responses for one operation.openapi_call validates and invokes an operation with bounded output.
It is plain ESM JavaScript, so installing from GitHub does not run a build or prepare script.
Why this plugin
Harness already gives an agent a shell. APIs still benefit from a narrower interface: operation discovery without reading a huge spec into the model context, declared-parameter validation, environment-backed credentials, read-only defaults, SSRF checks, and response limits. This plugin provides those controls without patching the Harness agent loop.
Install
dsh plugin --profile web add github:Degurechaff57/dsh-openapi
The bundle installs with an empty API catalog. Add API entries to your profile's cordis.patch.yml:
- id: openapi
config:
apis:
- id: petstore
source: https://petstore3.swagger.io/api/v3/openapi.json
baseUrl: https://petstore3.swagger.io/api/v3
allowedMethods: [GET, HEAD]
Start Harness and ask:
Use openapi_list to find the operation that lists pets, describe it, then call it.
For a source checkout, install the local directory instead:
dsh plugin --profile web add /absolute/path/to/dsh-openapi
Credentials
Keep secrets out of YAML. Map a request header to an environment variable:
- id: openapi
config:
apis:
- id: internal-api
source: ./openapi/internal.yml
baseUrl: https://api.example.com/v1
headers:
Accept: application/json
credentials:
- header: Authorization
env: INTERNAL_API_TOKEN
prefix: 'Bearer '
allowedMethods: [GET, HEAD, POST]
The credential header is applied after model-supplied header parameters, so a tool call cannot override it. Missing environment variables fail the call before network I/O.
Configuration
Top-level options:
| Field | Default | Purpose |
|---|
apis | [] | Configured API documents |
timeoutMs | 30000 | Per-call timeout |
maxSpecBytes | 2097152 | Maximum local or remote spec size |
maxResponseBytes | 262144 | Maximum response body returned to the model |
maxRedirects | 3 | Redirect limit; every destination is rechecked |
maxOperationsPerApi | 1000 | Catalog size limit per API |
Each apis entry accepts:
| Field | Default | Purpose |
|---|
id | required | Stable id used in tool calls |
source | required | HTTP(S) URL, file: URL, absolute path, or path relative to the Harness process |
baseUrl | spec server | Explicit API server override |
headers | {} | Static non-secret headers |
credentials | [] | Header/environment-variable mappings |
allowedMethods | [GET, HEAD] | Methods the tool may invoke |
allowPrivateNetwork | false | Opt in to loopback/private-network destinations |
Security defaults
- Specs are administrator-configured; the model cannot load an arbitrary spec at runtime.
- APIs start read-only: only
GET and HEAD are enabled.
- Calls accept only parameters declared by the selected operation.
- URL credentials, localhost names, private IP literals, and hostnames resolving to private IPs are blocked by default. Redirect destinations are checked again, and credentials are stripped on cross-origin redirects.
- Response bodies are capped and sensitive response headers such as
set-cookie are not returned.
- Credential values come from the environment, override call-supplied values, and are never included in tool results.
allowPrivateNetwork: true is necessary for local development servers. It is an explicit trust decision, not a substitute for a network sandbox. DNS can change between validation and connection, so do not use untrusted OpenAPI documents or hostile DNS infrastructure for high-assurance isolation.
Current scope
- OpenAPI 3.0 and 3.1 JSON/YAML
- Local
#/... references
- Common path, query, header, and cookie serialization
- JSON and text responses
Remote $ref documents and specialized serialization such as deepObject are intentionally not followed yet. The plugin fails loudly instead of making an ambiguous request.
DeepSeek Harness is in developer preview. This release is tested against the current source CLI (0.1.0-rc.5) and npm prerelease (0.1.0-rc.6); compatibility updates will follow upstream breaking changes.
Development
npm install
npm run check
The test suite covers parsing, references, catalog generation, request construction, credential precedence, method restrictions, private-network rejection, redirect validation, output truncation, and plugin registration.
License
MIT
