mcp-toolz

Instructions

Implementation Reference

• src/mcp_server/server.py:387-402 (handler)

  The main handler for the 'context_search' tool within the MCP server's call_tool method. It parses input arguments, determines the search mode (tags, query, or list), delegates to storage layer, formats results, and returns as TextContent.

  if name == "context_search":
      query = arguments.get("query")
      tags = arguments.get("tags")
      type_filter = arguments.get("type")
      limit = arguments.get("limit", 10)
  
      # If tags provided, search by tags; otherwise search by query
      if tags:
          contexts = self.storage.get_contexts_by_tags(tags, limit=limit)
      elif query:
          contexts = self.storage.search_contexts(query, type_filter=type_filter, limit=limit)
      else:
          contexts = self.storage.list_contexts(type_filter=type_filter, limit=limit)
  
      result = self._format_contexts_response(contexts)
      return [TextContent(type="text", text=result)]

• src/mcp_server/server.py:108-132 (registration)

  Registration of the 'context_search' tool in the MCP server's list_tools method, including name, description, and detailed input schema.

  Tool(
      name="context_search",
      description="Search Claude Code contexts by query string or tags",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {"type": "string", "description": "Search query"},
              "tags": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Filter by tags",
              },
              "type": {
                  "type": "string",
                  "description": "Filter by type (conversation, code, suggestion, error)",
                  "enum": ["conversation", "code", "suggestion", "error"],
              },
              "limit": {
                  "type": "integer",
                  "description": "Maximum number of results",
                  "default": 10,
              },
          },
      },
  ),

• src/mcp_server/server.py:111-131 (schema)

  JSON schema defining the input parameters for the context_search tool: query (string), tags (array of strings), type (enum), and limit (integer with default).

  inputSchema={
      "type": "object",
      "properties": {
          "query": {"type": "string", "description": "Search query"},
          "tags": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Filter by tags",
          },
          "type": {
              "type": "string",
              "description": "Filter by type (conversation, code, suggestion, error)",
              "enum": ["conversation", "code", "suggestion", "error"],
          },
          "limit": {
              "type": "integer",
              "description": "Maximum number of results",
              "default": 10,
          },
      },
  },

• src/context_manager/storage.py:234-257 (helper)

  Core search helper method in ContextStorage that performs SQL full-text LIKE searches on title, content, and tags columns, optionally filters by type, orders by timestamp, and limits results.

  def search_contexts(self, query: str, type_filter: str | None = None, limit: int = 10) -> list[ContextEntry]:
      """Search contexts by title, content, or tags."""
      sql_query = """
          SELECT * FROM contexts
          WHERE (
              title LIKE ? OR
              content LIKE ? OR
              tags LIKE ?
          )
      """
      params: list[Any] = [f"%{query}%", f"%{query}%", f"%{query}%"]
  
      if type_filter:
          sql_query += " AND type = ?"
          params.append(type_filter)
  
      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_context(row) for row in cursor.fetchall()]

• src/context_manager/storage.py:301-313 (helper)

  Helper method for tag-based filtering using dynamic SQL OR conditions on tags column with LIKE wildcards.

  def get_contexts_by_tags(self, tags: list[str], limit: int = 10) -> list[ContextEntry]:
      """Get contexts that match any of the given tags."""
      # Build OR conditions for each tag (using parameterized queries)
      conditions = " OR ".join(["tags LIKE ?"] * len(tags))
      # Safe: only concatenating placeholders, user data goes through params
      query = "SELECT * FROM contexts WHERE " + conditions + " ORDER BY timestamp DESC LIMIT ?"  # nosec B608
      params = [f"%{tag}%" for tag in tags] + [limit]
  
      with closing(sqlite3.connect(self.db_path)) as conn:
          conn.row_factory = sqlite3.Row
          cursor = conn.execute(query, params)
          return [self._row_to_context(row) for row in cursor.fetchall()]