feat(cli): clarify MCP is opt-in — REST primary, MCP for MCP-only clients

[rohitg00]

Summary

Today's boot output foregrounds MCP equally with REST, and the connect adapter logs say nothing about which protocol they're wiring. Users were reading this as MCP being required. It isn't — REST is the primary surface for hooks-supporting agents (Claude Code, Codex, OpenClaw, Hermes, pi, OpenHuman), and MCP is the bridge for MCP-only clients (Cursor, Gemini CLI, OpenCode, Cline, Goose, Kilo Code, Aider, Claude Desktop, Windsurf, Roo Code).

Three rewording passes, same numbers everywhere, no behavioral change.

1. Boot endpoints summary (src/index.ts)

Before:

```
Endpoints: 107 REST + 51 MCP tools + 6 MCP resources + 3 MCP prompts
```

After:

```
REST API: 107 endpoints at http://localhost:3111/agentmemory/*
MCP surface (opt-in via `npx @agentmemory/mcp`): 51 tools · 6 resources · 3 prompts
```

2. connect adapter pre-install lines

Added a protocolNote: string field on ConnectAdapter. runAdapter prints it once, right after the existing `Wiring …` step. Same field is plumbed through createJsonMcpAdapter so cursor/gemini-cli/openclaw set it too.

• claude-code, codex, openclaw, hermes (hooks-supporting agents wired via MCP):
  `→ Using MCP. Hooks are also available — see docs/.md.`
• pi, openhuman (hooks-supporting agents wired via REST/native extension):
  `→ Using native hooks (REST API at :3111). MCP not required.`
• cursor, gemini-cli (MCP-only clients):
  `→ Using MCP (the only protocol speaks). Memory bridge runs at :3111 underneath.`

3. mcp subcommand --help text (src/cli.ts)

Before: `mcp Start standalone MCP server (no engine required)`

After: `mcp Start standalone MCP shim — opt-in surface for MCP-only clients (Cursor, Gemini CLI, etc). REST always available at :3111.`

Why

Rohit pushed back directly: today's CLI surface reads as MCP-required. This is a copy fix that puts REST in the primary slot everywhere a user first encounters the protocol choice — boot output, connect, --help.

Test plan

• npm run build passes
• Full test suite: 954/954 pass (same as origin/main baseline)
• Diff stat: 13 files, +36/-2
• No README touch — that's a separate doc-only PR
• No version bump, no CHANGELOG entry
• No touching the CLI ready panel (sibling PR's surface area)

Summary by CodeRabbit

• Documentation
  • Updated help text to clarify MCP as a "standalone MCP shim" with opt-in surface while REST remains available.
  • Added protocol notes to all adapter configurations explaining whether they use MCP or native hooks.
  • Protocol notes now display during adapter connection setup.
  • Updated startup logging to separately display REST API and MCP endpoint information.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentmemory	Ready	Preview, Comment	May 15, 2026 4:19pm

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a protocolNote field to the adapter system to document whether each integration uses MCP or REST hooks, integrates it into the CLI connect workflow, and updates help text and boot logging to clarify protocol availability and surface options.

Changes

Protocol Notes Architecture

Layer / File(s)	Summary
Type system and factory foundation src/cli/connect/types.ts, src/cli/connect/json-mcp-adapter.ts	ConnectAdapter gains an optional protocolNote?: string field, JsonMcpAdapterConfig adds the same optional field, and createJsonMcpAdapter conditionally forwards the field into the returned adapter object.
Adapter protocol notes src/cli/connect/claude-code.ts, src/cli/connect/codex.ts, src/cli/connect/cursor.ts, src/cli/connect/gemini-cli.ts, src/cli/connect/hermes.ts, src/cli/connect/openclaw.ts, src/cli/connect/openhuman.ts, src/cli/connect/pi.ts	Each of the eight adapters now exports a protocolNote field describing whether it uses MCP or REST hooks at :3111.
CLI connect workflow integration src/cli/connect/index.ts	runAdapter logs the adapter's protocolNote message via p.log.message(...) immediately after the "Wiring …" step and before installation.
Help text and boot logging updates src/cli.ts, src/index.ts	CLI help text clarifies the mcp command as a standalone MCP shim with an opt-in surface; boot logging splits endpoints into separate REST API and MCP surface status lines with tool/resource/prompt counts.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• rohitg00/agentmemory#134: Updates the mcp command help text to reflect shim usage and protocol clarification.
• rohitg00/agentmemory#402: Introduces the adapter framework that this PR extends with the new protocolNote field and integration.

Poem

🐇 Whiskers twitch with glee,
Protocol notes now shine so clear—
MCP or REST hooks free,
Each adapter's purpose near,
Users know what they'll see! 🎀

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ 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 directly summarizes the main change: clarifying that MCP is opt-in with REST as the primary protocol, which matches the core objective across all file modifications.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/cli-mcp-reword

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

src/cli/connect/types.ts (1)

10-15: ⚡ Quick win

Drop the WHAT-style JSDoc on protocolNote and keep naming self-explanatory.

The new comment explains behavior in detail and conflicts with the repo rule to avoid WHAT-comments in TS files. Prefer a concise field name and no explanatory block here.

As per coding guidelines, src/**/*.ts: "Avoid code comments explaining WHAT — use clear naming instead".

🤖 Prompt for 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.

In `@src/cli/connect/types.ts` around lines 10 - 15, Remove the WHAT-style JSDoc
block above the protocolNote field and replace it with a concise,
self-explanatory name (rename protocolNote → protocolSummary) so the field
itself conveys purpose; keep no explanatory block comment, and update any usages
of protocolNote to protocolSummary.

🤖 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.

Nitpick comments:
In `@src/cli/connect/types.ts`:
- Around line 10-15: Remove the WHAT-style JSDoc block above the protocolNote
field and replace it with a concise, self-explanatory name (rename protocolNote
→ protocolSummary) so the field itself conveys purpose; keep no explanatory
block comment, and update any usages of protocolNote to protocolSummary.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8838a1ca-ca9f-42c0-8d8f-9c59f58932b6

📥 Commits

Reviewing files that changed from the base of the PR and between c3a613a and 1962e7c.

📒 Files selected for processing (13)

• src/cli.ts
• src/cli/connect/claude-code.ts
• src/cli/connect/codex.ts
• src/cli/connect/cursor.ts
• src/cli/connect/gemini-cli.ts
• src/cli/connect/hermes.ts
• src/cli/connect/index.ts
• src/cli/connect/json-mcp-adapter.ts
• src/cli/connect/openclaw.ts
• src/cli/connect/openhuman.ts
• src/cli/connect/pi.ts
• src/cli/connect/types.ts
• src/index.ts