conversations_by_date

Instructions

Implementation Reference

• brain_mcp/server/tools_conversations.py:106-127 (handler)

  Handler function for the 'conversations_by_date' MCP tool. Queries the DuckDB conversations view for conversations on a specific date (YYYY-MM-DD), returning a formatted markdown string with conversation IDs, titles, sources, and models.

  @mcp.tool()
  def conversations_by_date(date: str, limit: int = 30) -> str:
      """
      Get conversations from a specific date (YYYY-MM-DD format).
      """
      con = get_conversations()
      results = con.execute("""
          SELECT DISTINCT conversation_id, conversation_title, source, model, created
          FROM conversations
          WHERE CAST(created AS DATE) = CAST(? AS DATE)
          ORDER BY created DESC
          LIMIT ?
      """, [date, limit]).fetchall()
  
      if not results:
          return f"No conversations found on {date}"
  
      output = [f"## Conversations on {date} ({len(results)} found)\n"]
      for conv_id, title, source, model, _ in results:
          output.append(f"- **{title or 'Untitled'}**")
          output.append(f"  {source}/{model} | ID: {conv_id[:20]}...")
      return "\n".join(output)

• brain_mcp/server/tools_conversations.py:10-11 (registration)

  Registration function that registers the conversations_by_date tool (along with others) via the @mcp.tool() decorator. Called from server.py line 43.

  def register(mcp):
      """Register conversation tools with the MCP server."""

• brain_mcp/server/server.py:35-44 (registration)

  Server entry point imports and calls tools_conversations.register(mcp) which registers conversations_by_date as an MCP tool.

  from . import tools_conversations
  from . import tools_search
  from . import tools_synthesis
  from . import tools_stats
  from . import tools_prosthetic
  from . import tools_github
  from . import tools_analytics
  
  tools_conversations.register(mcp)
  tools_search.register(mcp)

• brain_mcp/server/db.py:147-170 (helper)

  Helper that provides the DuckDB connection with a conversations view over parquet data, used by the conversations_by_date handler to query conversation data.

  def get_conversations() -> duckdb.DuckDBPyConnection:
      """Get cached DuckDB connection with conversations view.
  
      Automatically checks for new source data and re-ingests if needed
      (lazy sync — no background threads, just mtime checks).
      """
      global _conversations_db
  
      # Lazy sync: check for new files before serving
      _check_and_sync()
  
      cfg = get_config()
      if _conversations_db is None:
          if not cfg.parquet_path.exists():
              raise FileNotFoundError(
                  f"Conversations parquet not found at {cfg.parquet_path}. "
                  "Run the ingest pipeline first."
              )
          _conversations_db = duckdb.connect()
          _conversations_db.execute(f"""
              CREATE VIEW IF NOT EXISTS conversations
              AS SELECT * FROM read_parquet('{cfg.parquet_path}')
          """)
      return _conversations_db

• brain_mcp/dashboard/routes/tools.py:186-192 (schema)

  Dashboard tool registry entry describing the conversations_by_date tool's name, description, category, required resources, parameters, and probe data for testing.

  {
      "name": "conversations_by_date",
      "description": "What happened on a specific date",
      "category": "Conversation",
      "requires": ["conversations"],
      "params": {"date": "str"},
      "probe": {"date": "2025-01-15"},