docs(readme): clarify MCP shim vs full server tool count (#233 gap 1)

[therahul-yo]

Summary

Addresses gap #1 from #233: users following the Cursor / OpenCode / Gemini CLI setup only see 7 tools and assume they misconfigured something.

The README implied the @agentmemory/mcp shim exposes "all 51 tools when AGENTMEMORY_TOOLS=all". In reality:

• AGENTMEMORY_TOOLS is a server-side flag (read by iii-engine), not by the shim — setting it in the shim's MCP env block does nothing.
• The shim has two modes:
  • Proxy — AGENTMEMORY_URL reaches a running agentmemory server → all 51 tools forwarded.
  • Local fallback — no server reachable → 7 hardcoded tools from src/mcp/standalone.ts (memory_save, memory_recall, memory_smart_search, memory_sessions, memory_export, memory_audit, memory_governance_delete).

Changes (README.md only)

1. Codex plugin bullet (L371): replace the misleading AGENTMEMORY_TOOLS=all qualifier with an accurate proxy/local mode description.
2. MCP Server section header (L733): new callout that enumerates the 7-tool local fallback set and explains how to unlock the full 51.

Verification

• Diff is 1 file / 3 insertions / 1 deletion.
• 7-tool list mirrors IMPLEMENTED_TOOLS in src/mcp/standalone.ts:16-23 verbatim.
• No code changes — pure documentation.

Note on scope

#233 documents 6 doc gaps in total. This PR addresses only gap 1 to keep the change focused and easy to review. The other gaps (stdio→HTTP MCP bridge docs, AGENTMEMORY_URL env-table entry, end-to-end self-hosted Ollama guide, Windows env_file gotcha, npm v11 + onnx-proto workaround) are independent and worth separate PRs.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified MCP shim tool availability behavior: the full 51-tool set is exposed when connected to an agentmemory server, with automatic fallback to a 7-tool local set when the server is unreachable.
  • Updated Codex integration documentation to reflect these tool availability changes and clarified server-side configuration behavior.

[vercel]

@therahul-yo is attempting to deploy a commit to the rohitg00's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 76620e37-a5ed-411b-9e94-4dff7200ab36

📥 Commits

Reviewing files that changed from the base of the PR and between 8b98432 and b56e869.

📒 Files selected for processing (1)

• README.md

---

📝 Walkthrough

Walkthrough

Updated README.md to clarify that @agentmemory/mcp exposes 51 tools in proxy mode (when AGENTMEMORY_URL reaches a running server) or 7 tools in local fallback mode. Documented that AGENTMEMORY_TOOLS=core|all is a server-side flag only.

Changes

MCP Shim Documentation Clarification

Layer / File(s)	Summary
MCP Shim Proxy vs Local Tool Availability README.md	Rewrote Codex integration MCP server description (line 371) to specify proxy-mode behavior (51 tools when AGENTMEMORY_URL points to running server) versus fallback behavior (7 local tools when unreachable); added new note (lines 734–735) explaining @agentmemory/mcp is a thin shim with server-reachability-dependent tool exposure and clarified that `AGENTMEMORY_TOOLS=core

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• rohitg00/agentmemory#233: Directly addresses documentation gaps for MCP shim's 7-tool vs 51-tool behavior and AGENTMEMORY_URL proxy behavior clarification.

Possibly related PRs

• rohitg00/agentmemory#280: Implements the functional proxy-vs-local behavior (livez probing and AGENTMEMORY_FORCE_PROXY escape hatch) that this PR now documents.
• rohitg00/agentmemory#270: Implements the proxy-mode tool forwarding logic in src/mcp/standalone.ts that this PR documents for users.
• rohitg00/agentmemory#282: Concurrent MCP documentation updates in README.md covering the same AGENTMEMORY_URL proxy-vs-local tool availability behavior.

Poem

🐰 A rabbit hops through docs so clear,
Explaining shims that shift and veer—
Fifty-one tools when server's near,
Seven when it's far, my dear!
Configuration flags now bright and true! 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: clarifying MCP shim tool count differences in README documentation, which is exactly what the PR accomplishes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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