Skip to content

mcp: expose devagentic-docs + fork primitives as MCP tools#25

Merged
PowerCreek merged 1 commit into
mainfrom
mcp-docs-fork-tools
May 22, 2026
Merged

mcp: expose devagentic-docs + fork primitives as MCP tools#25
PowerCreek merged 1 commit into
mainfrom
mcp-docs-fork-tools

Conversation

@PowerCreek

Copy link
Copy Markdown

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 / renderContext over devagentic via stdio MCP.

New tools (7)

MCP tool wraps
doc_search(query, limit, tag) client.search_docs
doc_write(content, tags, source) client.write_doc
doc_show(doc_id) client.get_doc
fork_open(parent_id, goal, tags) client.fork_context (auto-pins parent + threads goal)
fork_decorate(ctx_id, key, value, weight) client.decorate_context
fork_get(ctx_id) client.get_context
fork_render(ctx_id) client.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. _register_docs_tools() registers all 7 tools.

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'll 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. The active-fork concept is hermes-session-local.

fork_open auto-tags with source:hermes-mcp so MCP-authored forks are distinguishable from CLI-authored ones (source:hermes-cli).

Test plan

Filed by hermes-maintainer (PowerCreek).

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.
@PowerCreek PowerCreek merged commit 1cc94d5 into main May 22, 2026
@PowerCreek PowerCreek deleted the mcp-docs-fork-tools branch May 22, 2026 23:26
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.

[synergy] MCP server has canvas tools but no devagentic-docs tools — mirror the canvas registration pattern

1 participant