mcp: fix Gemini register_version schema + optional types

[leoric-crown]

This PR fixes the following failed MCP tool load in Gemini CLI:

❯ gemini
Skipping tool 'create_version' from MCP server 'archon' because it has missing types in its parameter schema.
Please file an issue with the owner of the MCP server.

Summary of changes:

• Constrain create_version content to JSON-serializable dict or list of dicts to satisfy Gemini/MCP schema expectations (avoid untyped Any).
• Use str or None for optional source_domain params in RAG tools.

Rationale:
These type adjustments align tool schemas with MCP expectations so Gemini recognizes the register version tools reliably.

Notes: No functional behavior changed beyond type annotations; low risk.

Summary by CodeRabbit

• Refactor

  • Tightened type for document version content to require JSON-serializable objects/arrays.
  • Made the “source domain” parameter explicitly optional in knowledge search and code example tools for consistency.

• Chores

  • Improved type safety and consistency; no runtime or API behavior changes.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Type annotations were tightened for public tool functions. The documents version tool now restricts content to JSON-serializable dict[str, Any] or list[dict[str, Any]]. In the RAG module, source_domain is explicitly optional (str | None). No control flow, HTTP behavior, or return types were changed.

Changes

Cohort / File(s)	Summary
Documents version tool typing python/src/mcp_server/features/documents/version_tools.py	Narrowed create_version content parameter from Any to `dict[str, Any]
RAG tools optional domain typing python/src/mcp_server/modules/rag_module.py	Updated perform_rag_query and search_code_examples signatures to use `str

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• mcp: fix Gemini register_version schema + optional types #562 — Tightens create_version content typing and updates source_domain typing in the same files (version_tools.py, rag_module.py).

Poem

I twitch my whiskers at types made clean,
Dicts in neat rows, lists crisp and lean.
RAG now knows when domains are none—
Optional paths, yet queries still run.
In burrows of code I softly cheer, hop-hop, my dear! 🐇

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d573528 and 5686714.

📒 Files selected for processing (1)

• python/src/mcp_server/features/documents/version_tools.py (1 hunks)

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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]

Actionable comments posted: 0

🧹 Nitpick comments (2)

python/src/mcp_server/features/documents/version_tools.py (1)

31-33: Good fix: constraining content removes bare Any from MCP schema; consider two small schema-oriented tweaks

• Consider typing field_name as a Literal to emit an enum in the tool schema, which helps Gemini/clients validate inputs earlier:

  from typing import Literal
  # ...
  async def create_version(
      ctx: Context,
      project_id: str,
      field_name: Literal["docs", "features", "data", "prd"],
      content: dict[str, Any] | list[dict[str, Any]],
      change_summary: str | None = None,
      document_id: str | None = None,
      created_by: str = "system",
  ) -> str:
      ...

• For consistency with Python 3.12 style used elsewhere in the PR, prefer str | None over Optional[str] for change_summary/document_id here (and the other tool functions in this file).

python/src/mcp_server/modules/rag_module.py (1)

81-81: Signature change to source_domain: str | None looks right; one minor semantics nit

Current check uses if source_domain: which ignores empty strings. If empty string should be treated as “provided but invalid,” switch to if source_domain is not None: and validate non-empty separately; otherwise, keep as-is.

Also applies to: 138-138

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 230f825 and d573528.

📒 Files selected for processing (2)

• python/src/mcp_server/features/documents/version_tools.py (1 hunks)
• python/src/mcp_server/modules/rag_module.py (2 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

python/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

python/**/*.py: Target Python 3.12 with a 120-character line length
Use Ruff for linting and Mypy for type checking before commit

Files:

• python/src/mcp_server/features/documents/version_tools.py
• python/src/mcp_server/modules/rag_module.py

{python/**/*.py,archon-ui-main/src/**/*.{ts,tsx,js,jsx}}

📄 CodeRabbit inference engine (CLAUDE.md)

{python/**/*.py,archon-ui-main/src/**/*.{ts,tsx,js,jsx}}: Remove dead code immediately; do not keep legacy/unused functions
Avoid comments that reference change history (e.g., LEGACY, CHANGED, REMOVED); keep comments focused on current functionality

Files:

• python/src/mcp_server/features/documents/version_tools.py
• python/src/mcp_server/modules/rag_module.py

[coleam00]

Thank you for this @leoric-crown!