Clarify MCP conversationId uniqueness guidance

[kentcdodds]

Summary

• clarify MCP tool instructions to tell clients to generate short random conversationId values that attempt to avoid collisions
• align the shared conversationId schema description with the top-level MCP server instructions
• dedupe repeated MCP conversationId guidance in packages/worker/src/mcp/index.ts via a shared exported constant

Testing

• npm run test:mcp

Summary by CodeRabbit

• Documentation
  • Updated MCP server instructions to clarify conversationId handling: clients should generate and reuse short random values, and Kody returns generated conversationIds in responses when omitted.

  

Summary by CodeRabbit

• Documentation
  • Updated MCP server instructions to clarify conversationId handling: clients should generate and reuse short random values, and Kody returns generated conversationIds in responses when omitted.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updated MCP server documentation and descriptions across two files to specify that clients should generate and reuse short random conversationId values to avoid collisions, with Kody generating and returning a short random value if omitted. No code logic or API changes were made.

Changes

Cohort / File(s)	Summary
MCP Server Documentation packages/worker/src/mcp/index.ts	Updated inline instructions across "Quick start", "How to use search", "How to use execute", and "MCP App tools" sections to clarify that clients should generate short random conversationId values and that Kody returns the generated ID in structuredContent.conversationId if omitted.
Tool Call Context Description packages/worker/src/mcp/tools/tool-call-context.ts	Updated conversationIdDescription string to reflect that clients should provide short random values for collision avoidance, and that Kody generates a short random value when omitted.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• Add MCP conversation and memory context plumbing #103: Modifies the same MCP tool-call context around conversationId semantics, adding conversationId handling utilities and schemas alongside this documentation update.
• Expose conversationId in MCP tool content #106: Updates conversationId behavior by exposing it in MCP tool responses and adjusting related code and tests to align with the new random generation semantics.

Poem

🐰 A random ID hops along the way,
Short and bouncy, it won't go astray!
Kody catches those that slip through the cracks,
Less confusion now on the conversation tracks! 🎯

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: updating MCP documentation to clarify how conversationId should be generated and used for uniqueness.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ 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 cursor/conversation-id-uniqueness-instructions-cfe3

---

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

[github-actions]

🔎 Preview deployed: https://kody-pr-108.kentcdodds.workers.dev

Worker: kody-pr-108
D1: kody-pr-108-db
KV: kody-pr-108-oauth-kv

Mocks:

• ai: https://kody-pr-108-mock-ai.kentcdodds.workers.dev/__mocks (kody-pr-108-mock-ai)
• cloudflare: https://kody-pr-108-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-108-mock-cloudflare)
• cursor: https://kody-pr-108-mock-cursor.kentcdodds.workers.dev/__mocks (kody-pr-108-mock-cursor)
• github: https://kody-pr-108-mock-github.kentcdodds.workers.dev/__mocks (kody-pr-108-mock-github)
• resend: https://kody-pr-108-mock-resend.kentcdodds.workers.dev/__mocks (kody-pr-108-mock-resend)

[coderabbitai]

🧹 Nitpick comments (1)

packages/worker/src/mcp/index.ts (1)

35-35: Consider centralizing the repeated conversationId instruction text.

Lines 35, 54, 84, and 105 duplicate near-identical wording. Extracting a shared constant (like conversationIdGuidance) would reduce doc drift risk.

♻️ Suggested refactor

+const conversationIdGuidance =
+  "Optionally pass `conversationId` and reuse it on later related tool calls. Generate short random values that attempt to avoid collisions. If omitted, Kody generates a short random value and returns it in `structuredContent.conversationId`."
...
-- Optionally pass `conversationId` and reuse it on later related tool calls. Generate short random values that attempt to avoid collisions. If omitted, Kody generates a short random value and returns it in `structuredContent.conversationId`.
+- ${conversationIdGuidance}

Also applies to: 54-54, 84-84, 105-105

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/worker/src/mcp/index.ts` at line 35, Extract the duplicated
"conversationId" instruction string in packages/worker/src/mcp/index.ts into a
single exported constant (e.g., conversationIdGuidance) and replace the repeated
inline texts at the four occurrences with that constant; update any local
references in the same module to use conversationIdGuidance and export it if
other modules consume the guidance so callers still receive identical wording.
Ensure the constant contains the exact original wording including mention of
optional conversationId and memoryContext, and run/adjust any tests or callers
that compare the text to reference the new constant instead of the hardcoded
string.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/worker/src/mcp/index.ts`:
- Line 35: Extract the duplicated "conversationId" instruction string in
packages/worker/src/mcp/index.ts into a single exported constant (e.g.,
conversationIdGuidance) and replace the repeated inline texts at the four
occurrences with that constant; update any local references in the same module
to use conversationIdGuidance and export it if other modules consume the
guidance so callers still receive identical wording. Ensure the constant
contains the exact original wording including mention of optional conversationId
and memoryContext, and run/adjust any tests or callers that compare the text to
reference the new constant instead of the hardcoded string.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a0fc87d1-549c-4578-80d4-b8126d2872f4

📥 Commits

Reviewing files that changed from the base of the PR and between 38aaba0 and bd8eb54.

📒 Files selected for processing (2)

• packages/worker/src/mcp/index.ts
• packages/worker/src/mcp/tools/tool-call-context.ts