feat(mcp): surface a server's own instructions when it has no description

[yh928]

Summary

• Connection now keeps the instructions an MCP server returns from initialize, and ConnectedServerOverview carries them through to the prompt.
• The orchestrator's connected-server block falls back to those instructions only when the registry has no description, so nothing that reads well today changes.
• The text is untrusted third-party input reaching a system prompt, so it is sanitized and capped before use.

Problem

An MCP server's initialize response carries instructions — the server's own statement of what it is for and how to drive it. We asked for it, discarded it, and told the agent nothing.

That was survivable while every connected server came from the registry inventory, which carries a curated description. Hand-entered custom servers (#5033) have no inventory entry, so the orchestrator prompt listed them by name and tool count alone and the agent had to infer the server's purpose from tool names.

Solution

A three-step ladder in format_connected_mcp_block: registry description → server instructions → tool count. The description keeps priority deliberately — it is curated, the instructions are whatever the server author wrote.

Instructions pass through sanitize_for_llm with a 600-character cap and flattened newlines. This is a third party's text landing in our system prompt, so it is treated as untrusted the same way skill descriptions are.

Submission Checklist

• Tests added or updated (happy path + at least one failure / edge case) — three cases: instructions used when there is no description, description preferred when there is one, and untrusted instructions sanitized
• Diff coverage ≥ 80% — the ladder and the sanitize path are both covered by the new tests
• N/A: behaviour-only change, no feature row added/removed/renamed — Coverage matrix updated
• No new external network dependencies introduced
• N/A: no release-cut surface touched — Manual smoke checklist updated
• Linked issue closed via Closes #NNN in the ## Related section

Impact

• Prompt-surface only. A server that already has a registry description renders byte-identically.
• Security: the new text is untrusted and is sanitized on the way in; that is the only new data path.

Related

Closes #5317

Summary by CodeRabbit

• Improvements

  • Connected MCP servers now display their provided instructions when a registry description is unavailable.
  • Existing registry descriptions remain the preferred source of server information.
  • Server instructions are sanitized and length-limited to keep displayed content safe and manageable.

• Reliability

  • Improved event-bus readiness handling for group and learning workflows, helping ensure actions occur only after the system is ready.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: c3819000-661f-4907-9e67-7cd167a23bc6

📥 Commits

Reviewing files that changed from the base of the PR and between 9f6dbe8 and a04e59b.

📒 Files selected for processing (6)

• src/core/jsonrpc.rs
• src/core/jsonrpc_tests.rs
• src/openhuman/agent/agent_tests_part_03_tests.rs
• src/openhuman/agent/registry/agents/orchestrator/prompt.rs
• src/openhuman/agent/registry/agents/orchestrator/prompt_tests.rs
• vendor/tinymcp

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds sanitized MCP server instructions as a prompt fallback, updates core event-bus readiness checks, changes related tests to current bus and retaining-memory helpers, and updates the vendored tinymcp reference.

Changes

MCP prompt fallback

Layer / File(s)	Summary
Prompt fallback and validation src/openhuman/agent/registry/agents/orchestrator/prompt.rs, src/openhuman/agent/registry/agents/orchestrator/prompt_tests.rs, vendor/tinymcp	Connected MCP entries prefer registry descriptions, then sanitized server instructions, then tool counts. Tests cover precedence, fence removal, and the 600-byte instruction limit. The tinymcp submodule reference is updated.

Core bus readiness

Layer / File(s)	Summary
Core bus readiness checks src/core/jsonrpc.rs, src/core/jsonrpc_tests.rs	JSON-RPC registration checks use BUS.is_initialised(). The wrapper test initializes the core bus asynchronously.

Autosave test storage

Layer / File(s)	Summary
Autosave test storage src/openhuman/agent/agent_tests_part_03_tests.rs	Four autosave origin-gating tests use retaining memory while preserving their assertions and polling behavior.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant MCPServer
  participant ConnectedServerOverview
  participant OrchestratorPrompt
  MCPServer->>ConnectedServerOverview: Provide instructions
  ConnectedServerOverview->>OrchestratorPrompt: Supply description, instructions, and tool count
  OrchestratorPrompt->>OrchestratorPrompt: Sanitize and bound fallback instructions

Loading

Suggested labels: feature, rust-core, agent

Suggested reviewers: senamakel, m3ga-mind

Merge Risk: ⚪ Minimal · up to a04e5

No actionable merge-blocking risk is confirmed in the current changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR also changes unrelated event-bus readiness logic in src/core/jsonrpc.rs, updates its test setup, and changes storage backends in four autosave tests. These changes do not implement or support…	Remove the unrelated event-bus and autosave test changes from this PR, or link them to a separate coding requirement.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: using an MCP server's instructions as a fallback when no registry description exists.
Linked Issues check	✅ Passed	The PR meets the coding requirements in [#5317]. The tinymcp revision is updated to expose the handshake instructions through ConnectedServerOverview. prompt.rs keeps a registry description firs…
Docstring Coverage	✅ Passed	Docstring coverage is 88.24% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 5 files. (1 skipped: 1 …

Full details: Out of Scope Changes check

Explanation

The PR also changes unrelated event-bus readiness logic in src/core/jsonrpc.rs, updates its test setup, and changes storage backends in four autosave tests. These changes do not implement or support [#5317].

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

---

_{A rabbit found instructions bright,
And tucked them in the prompt just right.
Descriptions still lead the way,
Safe bounds guard what servers say.
The core bus wakes with steady cheer,
While tests store memories clear.}

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/openhuman/agent_registry/agents/orchestrator/prompt.rs`:
- Around line 669-686: Extend
connected_mcp_block_sanitizes_untrusted_instructions to use instructions
containing newline and tab characters plus content exceeding the 600-byte limit.
Assert the rendered server item is capped at the defined 600-byte boundary and
contains no newline or tab characters, while preserving the existing
instruction-fence sanitization and server-name assertions.

In `@src/openhuman/mcp_registry/connections.rs`:
- Around line 174-178: Add stdio and HTTP connection tests covering the
initialization-to-overview propagation: have each initialize branch return
distinct instructions, then assert the resulting connected_overview retains the
corresponding value from Connection.instructions. Update the existing connection
test coverage near the initialize and overview construction paths without
changing production behavior.

In `@src/openhuman/mcp_registry/types.rs`:
- Around line 75-78: Add focused tests for the Transport::is_http_remote
discriminator, asserting Transport::Stdio returns false and
Transport::HttpRemote returns true. Place the coverage alongside the existing
Transport tests and construct each variant with the required fields.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 64b7d89f-789d-449f-bb72-a85d2f13c6f5

📥 Commits

Reviewing files that changed from the base of the PR and between a52a599 and a80330c.

📒 Files selected for processing (3)

• src/openhuman/agent_registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp_registry/connections.rs
• src/openhuman/mcp_registry/types.rs

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a80330cee1

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[greptile-apps]

Greptile Summary

This PR surfaces MCP server instructions (from the initialize handshake) in the orchestrator prompt as a fallback for custom servers that have no registry description, sanitizing the text through sanitize_for_llm with a 600-byte cap. The three-step ladder (registry description → server instructions → tool-count) is a clean design and the security intent is sound.

• Connection and ConnectedServerOverview now carry instructions: Option<String>, populated from both Stdio and HttpRemote initialize calls.
• format_connected_mcp_block in prompt.rs adds the fallback branch and three well-scoped tests, but references crate::openhuman::mcp_client::sanitize::sanitize_for_llm — a module path that does not exist; the correct path used elsewhere is crate::openhuman::util::sanitize::sanitize_for_llm, and this will fail to compile.

Confidence Score: 2/5

Not safe to merge: the instructions sanitization in prompt.rs references crate::openhuman::mcp_client::sanitize, a module that does not exist, which will cause a compile failure.

The only changed file that is not straightforwardly correct is prompt.rs, where the new instructions sanitization call uses crate::openhuman::mcp_client::sanitize::sanitize_for_llm — a path that resolves to nothing in this codebase. Every other call site uses crate::openhuman::util::sanitize::sanitize_for_llm. The build will fail until this is corrected.

Files Needing Attention: src/openhuman/agent/registry/agents/orchestrator/prompt.rs — the wrong sanitize module path on the instructions branch.

Important Files Changed

Filename	Overview
src/openhuman/agent/registry/agents/orchestrator/prompt.rs	Adds instruction fallback and three tests; the instructions sanitization call references a non-existent module path (mcp_client::sanitize vs util::sanitize), causing a compile failure.
src/openhuman/mcp/registry/connections.rs	Correctly captures init.instructions from both Stdio and HttpRemote branches and threads it through to Connection and connected_overview.
src/openhuman/mcp/registry/types.rs	Adds instructions: Option<String> field to ConnectedServerOverview with clear documentation; straightforward and correct.

_{Reviews (3): Last reviewed commit: "feat(mcp): surface a server's own instru..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/openhuman/mcp_registry/types.rs`:
- Around line 195-208: Add coverage in the mcp_registry test module for
format_connected_mcp_block() and serializable ConnectedServerOverview data:
verify a non-empty description takes precedence over instructions, instruction
text is sanitized before rendering, and the rendered instruction fallback is
capped at 600 bytes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ff9b3c43-077e-4751-8fb5-184232aec0ee

📥 Commits

Reviewing files that changed from the base of the PR and between a80330c and 2073e7f.

📒 Files selected for processing (3)

• src/openhuman/agent_registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp_registry/connections.rs
• src/openhuman/mcp_registry/types.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• src/openhuman/agent_registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp_registry/connections.rs

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/openhuman/agent/registry/agents/orchestrator/prompt.rs`:
- Around line 207-232: Split the oversized files by extracting the connected-MCP
block formatting around prompt.rs lines 207-232 into a focused module, and move
its formatter tests from prompt.rs lines 613-686 alongside it; update prompt.rs
to call the extracted formatter while preserving current description,
instructions sanitization, and fallback behavior. Extract the connection
initialization workflow from connections.rs lines 404-481 into a focused MCP
registry module, updating callers and imports without changing its behavior.
Ensure the resulting files remain at or below 500 lines.

In `@src/openhuman/mcp/registry/connections.rs`:
- Around line 417-418: Update the initialize call in the active client setup
flow around stdio.initialize() and the corresponding additional transport path
to emit [rpc] debug events immediately before and after each RPC. Include
server_id and transport on both events, and include instructions_present on the
completion event without logging instruction contents; preserve the existing
initialization result and error propagation.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a970da01-e469-4e8c-badc-9331f2b0fe6e

📥 Commits

Reviewing files that changed from the base of the PR and between d75b0a4 and 3c96df9.

📒 Files selected for processing (3)

• src/openhuman/agent/registry/agents/orchestrator/prompt.rs
• src/openhuman/mcp/registry/connections.rs
• src/openhuman/mcp/registry/types.rs

[greptile-apps]

yh928 has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[greptile-apps]

yh928 has reached the 50-credit limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[M3gA-Mind]

Maintainer review pass (review only — no approval, and nothing pushed to your branch). Checked against current main (fa044d388) and against the pinned vendor/tinymcp (55483d236).

The idea is good and still wanted — but this PR has become a cross-repo change, and I don't think that's obvious from the conflict output. Please read §1 before you attempt the rebase; two of your three files can no longer be edited in this repo at all.

1. connections.rs and types.rs are gone, and their contents moved to tinymcp

git reports:

CONFLICT (modify/delete): src/openhuman/mcp/registry/connections.rs deleted in main and modified in this branch
CONFLICT (modify/delete): src/openhuman/mcp/registry/types.rs      deleted in main and modified in this branch

Both were removed in b586de87e — "Remove files resurrected by a mistaken checkout" — as part of a batch that also took out mcp/audit/, mcp/config_servers/ and mcp/http_client/. They are not coming back.

The module paths survive, which is what makes this confusing: mcp/registry/mod.rs still declares pub mod types and pub mod connections, but they are now thin re-export shims —

pub mod types {
    pub use tinymcp_bus::{ …, ConnectedServerOverview, … };
}

pub mod connections {
    pub use tinymcp_bus::ConnectedServerOverview;
    pub async fn connected_overview() -> Vec<ConnectedServerOverview> {
        match host::try_service() { Some(s) => s.dynamic().connected_overview().await, None => Vec::new() }
    }
}

tinymcp owns the connection map now; openhuman only looks through it. So your +42/-5 and +13/-1 hunks have no file to land in — ConnectedServerOverview is defined at crates/tinymcp-bus/src/registry/types.rs:247 in tinyhumansai/tinymcp, and at the pinned commit its fields are exactly server_id, qualified_name, display_name, description, tools. No instructions.

The good news, and it is genuinely good: tinymcp already captures what you need. crates/tinymcp-bus/src/transport/types.rs:169 has

/// Free-form guidance the server wants the client to have.
///
/// Untrusted remote text. Sanitize before placing it in an LLM's context.
#[serde(default)]
pub instructions: Option<String>,

on the initialize-handshake type — parsed, retained, and already carrying the exact untrusted-text warning your design is built around. So the upstream work is not "capture instructions"; it is only "carry the field one layer up into ConnectedServerOverview". That is a small change.

There is also a nice piece of corroboration for your premise sitting in that struct's own doc comment: tools is documented as "Kept in full so a host can fall back to a tool count when a server has no description" — the fallback you are trying to improve on is described upstream as the current state of the art.

What this means in practice

This becomes three deliverables, in order:

1. tinyhumansai/tinymcp — add instructions: Option<String> to ConnectedServerOverview and populate it from the retained handshake value. #[serde(default)] keeps the bus contract backward-compatible.
2. tinyhumansai/openhuman — bump the vendor/tinymcp gitlink to the commit from (1). Worth saying out loud because it is easy to assume the pin bump rides along with the upstream merge: it does not, and a merged upstream PR delivers nothing to this repo until the pin moves.
3. This PR — keep only the prompt.rs hunks, rebased on (2).

If you'd rather not carry a cross-repo change, say so on this PR and I'll flag it to the maintainers — the openhuman half is small enough that it may be worth someone else taking the tinymcp side.

2. The prompt.rs half rebases cleanly and is unaffected

format_connected_mcp_block is still at prompt.rs:180, still takes &[…connections::ConnectedServerOverview], and still does the description-sanitize dance your ladder slots into. Its conflict is ordinary content drift, not a relocation. Once the field exists, this half is a straight rebase.

3. One small thing to reconcile while you're there

prompt.rs currently caps both untrusted strings at 240 bytes — skill descriptions at :143 and MCP descriptions at :218 — and your instructions cap is 600. I don't think that's wrong (instructions are a paragraph by nature, descriptions are a line), but three sanitize calls in one file with two different caps will draw a reviewer's question. A half-sentence on why 600 is the right number for this one input would settle it in advance.

Otherwise this is in good shape

Every check is green (14 pass, 6 skipped), CodeRabbit approved, and there are no unresolved review threads. The design calls — registry description keeps priority over server-authored text, and the instructions go through sanitize_for_llm because they are a third party's words landing in a system prompt — are both the right ones, and the second is the reason this needs to be done carefully rather than quickly. None of §1 is a criticism of the work; the ground moved under it.

[yh928]

Confirmed against main (8e65c4008) and the pinned vendor/tinymcp — your §1 is right and it changes what this PR is.

mcp/registry/{connections,types}.rs are re-export shims over tinymcp_bus now, so ConnectedServerOverview is defined in tinyhumansai/tinymcp and the +42/-5 and +13/-1 hunks have no file to land in. What is not affected is the part that carries the idea: agent/registry/agents/orchestrator/prompt.rs still exists and format_connected_mcp_block is still the function that decides what a connected server's line says. That change applies cleanly.

So the dependency is narrow and one-directional — one field:

• tinymcp — add instructions: Option<String> to ConnectedServerOverview, populated from the server's initialize handshake (the protocol already returns it; it is being dropped).
• openhuman — this PR's format_connected_mcp_block change, unchanged: fall back to instructions only when the registry description is empty, through the same sanitize_for_llm scrub at a wider bound, and keep the tool-count fallback beneath both. Its three tests need instructions: added to the existing ConnectedServerOverview literals, which is mechanical.

Nothing about the reasoning changed: a hand-added server has no registry entry and so no description, and its own initialize instructions are the only thing that can tell the orchestrator what it is for — otherwise the line degrades to a name plus "N tools available", which is what it does today.

I have not opened the tinymcp PR — different repo, its own review, and not something to do silently as part of a rebase. Options:

1. Add the field upstream in tinymcp, then rebase this PR down to the prompt change alone (it becomes small and self-contained); or
2. Close this and refile once the field exists.

(1) is my preference. Happy to open it on your say-so.

[yh928]

Upstream PR opened: tinyhumansai/tinymcp#14

That is the half that had to move. Once it merges this PR reduces to the openhuman-side consumer change (plus a submodule bump), which I'll rebase down to then.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9fe1b652ea

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4ab9517a4b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.

[chatgpt-codex-connector]

You have reached your Codex usage limits for security reviews. Please try again later.