mcp-toolz

Instructions

Implementation Reference

• src/mcp_server/server.py:466-472 (handler)

  MCP tool handler for 'todo_search' that extracts parameters, calls storage.search_todo_snapshots, formats results using _format_todo_snapshots_response, and returns TextContent.

  if name == "todo_search":
      query = arguments["query"]
      project_path = arguments.get("project_path")
      limit = arguments.get("limit", 10)
      snapshots = self.storage.search_todo_snapshots(query, project_path=project_path, limit=limit)
      result = self._format_todo_snapshots_response(snapshots)
      return [TextContent(type="text", text=result)]

• src/mcp_server/server.py:204-219 (schema)

  Input schema defining parameters for the todo_search tool: query (required), project_path (optional filter), limit (default 10).

  inputSchema={
      "type": "object",
      "properties": {
          "query": {"type": "string", "description": "Search query"},
          "project_path": {
              "type": "string",
              "description": "Filter by project path",
          },
          "limit": {
              "type": "integer",
              "description": "Maximum number of results",
              "default": 10,
          },
      },
      "required": ["query"],
  },

• src/mcp_server/server.py:201-220 (registration)

  Registration of the 'todo_search' tool in the list_tools() method's return list, including name, description, and schema.

  Tool(
      name="todo_search",
      description="Search todo snapshots by content or context description",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {"type": "string", "description": "Search query"},
              "project_path": {
                  "type": "string",
                  "description": "Filter by project path",
              },
              "limit": {
                  "type": "integer",
                  "description": "Maximum number of results",
                  "default": 10,
              },
          },
          "required": ["query"],
      },
  ),

• src/context_manager/storage.py:462-488 (helper)

  Core helper method implementing the search logic: SQL query with LIKE on 'todos' JSON field and 'context' field, optional project_path filter, ordered by timestamp DESC, limited results, converts rows to TodoListSnapshot objects.

  def search_todo_snapshots(
      self,
      query: str,
      project_path: str | None = None,
      limit: int = 10,
  ) -> list[TodoListSnapshot]:
      """Search todo snapshots by content or context description."""
      sql_query = """
          SELECT * FROM todo_snapshots
          WHERE (
              todos LIKE ? OR
              context LIKE ?
          )
      """
      params: list[Any] = [f"%{query}%", f"%{query}%"]
  
      if project_path:
          sql_query += " AND project_path = ?"
          params.append(project_path)
  
      sql_query += " ORDER BY timestamp DESC LIMIT ?"
      params.append(limit)
  
      with closing(sqlite3.connect(self.db_path)) as conn:
          conn.row_factory = sqlite3.Row
          cursor = conn.execute(sql_query, params)
          return [self._row_to_todo_snapshot(row) for row in cursor.fetchall()]

• src/mcp_server/server.py:688-709 (helper)

  Helper function to format the list of todo snapshots into a readable string response, showing active status, progress, project, ID, timestamp, and context.

  def _format_todo_snapshots_response(self, snapshots: list[Any]) -> str:
      """Format a list of todo snapshots for response."""
      from models import TodoListSnapshot
  
      if not snapshots:
          return "No todo snapshots found."
  
      lines = [f"Found {len(snapshots)} todo snapshots:\n"]
      for snapshot in snapshots:
          if isinstance(snapshot, TodoListSnapshot):
              active_icon = "★" if snapshot.is_active else "○"
              completed = sum(1 for t in snapshot.todos if t.status == "completed")
              total = len(snapshot.todos)
              context_str = f" - {snapshot.context}" if snapshot.context else ""
  
              lines.append(
                  f"{active_icon} {snapshot.timestamp.isoformat()}\n"
                  f"   ID: {snapshot.id}\n"
                  f"   Project: {snapshot.project_path}\n"
                  f"   Progress: {completed}/{total} completed{context_str}\n"
              )
      return "\n".join(lines)