mcp: expose devagentic-docs + fork primitives as MCP tools#25
Merged
Conversation
Mirrors the canvas-tools pattern (#56) for the just-shipped devagentic-docs plugin (#12 / PRs #19+#20+#23). MCP-aware clients (Claude Code, Cursor, Codex) can now writeDoc / searchDocs / forkContext / decorateContext / renderContext against any devagentic instance hermes is configured for. New tools (7): - doc_search(query, limit, tag) → search_docs - doc_write(content, tags, source) → write_doc - doc_show(doc_id) → get_doc - fork_open(parent_id, goal, tags) → fork_context (auto-pins parent + threads goal) - fork_decorate(ctx_id, key, value, weight) → decorate_context - fork_get(ctx_id) → get_context - fork_render(ctx_id) → render_context (envelope: {ctx_id, rendered}) Loader pattern: _resolve_docs_client() mirrors _resolve_canvas_client at line 880 — file-path import of plugins/devagentic-docs/client.py since the hyphenated dir isn't a Python package. Failure semantics: every tool returns {"error": "<msg>"} JSON. The plugin's last_error_text() pattern (introduced in #15) threads through via a _reason() helper, so federated agents see the same actionable hints CLI users get — e.g. on the canonical devbox deployment (where /graphql isn't exposed, see #21), they'd see "not found at <url>/graphql ..." instead of an opaque None. Out of scope per #24: fork_close + fork_pin depend on the session-local $HERMES_HOME/docs-fork-active marker, which doesn't translate to MCP's stateless tool model. fork_open auto-tags with source:hermes-mcp so MCP-authored forks are distinguishable from CLI-authored ones (source:hermes-cli). Tests: 22 new (tests/test_mcp_docs.py) covering registration, plugin-missing fallback, arg routing, last_error surfacing for the #21 case, and the real-import smoke. All passing alongside canvas MCP suite (14 existing) and the broader devagentic- adjacent test set (159 total). Closes #24.
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.
Summary
Closes #24. Mirrors the canvas-tools pattern (#56) for the just-shipped devagentic-docs plugin (#12 / PRs #19+#20+#23). MCP-aware clients (Claude Code, Cursor, Codex) can now call
writeDoc/searchDocs/forkContext/decorateContext/renderContextover devagentic via stdio MCP.New tools (7)
doc_search(query, limit, tag)client.search_docsdoc_write(content, tags, source)client.write_docdoc_show(doc_id)client.get_docfork_open(parent_id, goal, tags)client.fork_context(auto-pins parent + threads goal)fork_decorate(ctx_id, key, value, weight)client.decorate_contextfork_get(ctx_id)client.get_contextfork_render(ctx_id)client.render_context(envelope:{ctx_id, rendered})Loader pattern
_resolve_docs_client()mirrors_resolve_canvas_clientat line 880 — file-path import ofplugins/devagentic-docs/client.pysince the hyphenated dir isn't a Python package._register_docs_tools()registers all 7 tools.Failure semantics
Every tool returns
{"error": "<msg>"}JSON. The plugin'slast_error_text()pattern (introduced in #15) threads through via a_reason()helper, so federated agents see the same actionable hints CLI users get — e.g. on the canonical devbox deployment (where/graphqlisn't exposed, see #21), they'll see"not found at <url>/graphql ..."instead of an opaque None.Out of scope per #24
fork_close+fork_pindepend on the session-local$HERMES_HOME/docs-fork-activemarker, which doesn't translate to MCP's stateless tool model. The active-fork concept is hermes-session-local.fork_openauto-tags withsource:hermes-mcpso MCP-authored forks are distinguishable from CLI-authored ones (source:hermes-cli).Test plan
tests/test_mcp_docs.py:/graphql404 [synergy] Devagentic GraphQL adapters silently 404 — /graphql isn't exposed over HTTP on the canonical deployment #21 case)pytest tests/test_mcp_docs.py tests/test_mcp_canvas.py→ 36 passedFiled by hermes-maintainer (PowerCreek).