Repository navigation
feat(server): REST routes per tool; API reference generated from the tool registry - #107
Merged
Merged
Conversation
…tool registry vayl-server serves POST /v1/tools/<name> and GET /v1/tools behind the same auth as /mcp. Calls go through FastMCP's call_tool, so validation, the _guard capability and scope checks, audit and metrics match MCP exactly; errors map to 400/401/403/404/422. openapi/generate.py builds openapi/vayl-server.yaml (from base.yaml plus one typed operation per tool: schema, capability, annotations) and the API Reference tool pages. openapi/capture_examples.py records a real request/response for all 32 tools (fictional patient, clinical preset, gpt-6-luna). A test fails if the committed spec or pages are stale.
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The API Reference had one generic
POST /mcpoperation with an untyped JSON-RPC body, so no tool's arguments or response were visible. OpenAPI can't describe 32 tools on one path, so this adds real routes.REST routes (
src/vayl/api/rest.py, mounted at/v1behind the sameAuthMiddleware, body cap, rate limit and request IDs as/mcp):POST /v1/tools/<name>: JSON arguments in,{"result": "..."}outGET /v1/tools: the tools with their JSON Schemas (same as MCPtools/list)call_tool, so validation,_guardcapability/scope checks, audit and metrics are identical to MCP400non-object body ·401no key ·403missing capability or scope ·404unknown tool ·422bad arguments (pydantic's message indetail)Generated reference:
openapi/base.yaml: the hand-written parts (/mcp, probes, metrics, shared components)openapi/generate.py: writesopenapi/vayl-server.yaml(one typed operation per tool, with its capability from_guard, MCP annotations and example) anddocs/api-reference/tools/*.md(one page per group, each tool anopenapi-operationblock like the MCP endpoint page)openapi/capture_examples.py: drives all 32 tools through the REST routes with a real model and saves the examples; every example is a real 200 response, API keys redactedgenerate.py --checkmust passopenapi-spec-validator0.7.1)Docs: API Reference home rewritten for developers (curl quick start with real output, endpoint table, auth, status codes, REST vs MCP); "Calling Vayl from code", the MCP tools overview and HTTP endpoints mention the REST routes.
Found while capturing, not fixed here: in about 1 of 8 runs, "Warfarin stopped today. Started apixaban…" was stored as an
ADDof apixaban plus anARCHIVEof the stop, which skips the approval gate and leaves warfarin active. Tracked separately.