Skip to content

feat: add the okf mcp read tool surface - #26

Merged
leoafarias merged 1 commit into
mainfrom
feature/11-mcp-read-surface
Aug 21, 2026
Merged

feat: add the okf mcp read tool surface#26
leoafarias merged 1 commit into
mainfrom
feature/11-mcp-read-surface

Conversation

@chrishiguto

@chrishiguto chrishiguto commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Why

Agents need a sanctioned read surface that reproduces CLI and CI judgments without stale bundle state or protocol-channel noise.

What

okf mcp <bundle> serves four fixed tools over stdio: list-concepts, lookup-concept, query-graph, and validate. Every call re-reads the bundle. Stdout carries JSON-RPC only; diagnostics go to stderr.

validate returns the closed Spec report plus the adapter Verdict and supports the CLI-equivalent strict input. query-graph advertises OkfGraphQuery.jsonSchema verbatim and returns the versioned graph payload. All tools explicitly advertise read-only, non-destructive, idempotent, closed-world behavior.

Reviewer's guide

Start with lib/src/mcp/read_server.dart, then the real subprocess protocol harness in test/mcp_server_test.dart and the CLI wiring in lib/src/cli.dart.

Testing

  • Formatting and fatal-info analysis are clean.
  • All 156 tests pass.
  • The stdio harness exercises every tool, Report/Verdict parity, exact graph-query schema reuse, bad inputs, partial bundles, pure JSON-RPC output, session recovery, and graceful EOF shutdown.
  • MCP-only tests pass on Dart 3.4.0.
  • dart pub publish --dry-run reports 0 warnings.

Links

Cleanly restacked on the merged prepared-change foundation.

Fixes #11.

@chrishiguto
chrishiguto force-pushed the feature/11-mcp-read-surface branch from 7d91428 to 766d4e5 Compare August 18, 2026 19:41
@chrishiguto
chrishiguto changed the base branch from feature/10-graph-query-filters to feature/16-bundle-change-set August 18, 2026 19:41
@chrishiguto

Copy link
Copy Markdown
Contributor Author

Rebased onto feature/16-bundle-change-set and retargeted, so the stack stays linear for the write verbs (#12/#13), which need this read surface and the change-set in one branch. No content change from the reviewed version — the rebase was clean and the suite is green at 111 tests on the new base.

@chrishiguto
chrishiguto force-pushed the feature/11-mcp-read-surface branch 2 times, most recently from e0054e8 to 26fd807 Compare August 19, 2026 14:33
Base automatically changed from feature/16-bundle-change-set to main August 21, 2026 16:55
@leoafarias
leoafarias force-pushed the feature/11-mcp-read-surface branch from 64a1e3d to 2eee26d Compare August 21, 2026 17:08
@leoafarias
leoafarias merged commit fc4b0f6 into main Aug 21, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MCP server: read surface

2 participants