Knowledge Base MCP Server

Instructions

Implementation Reference

• src/knowledge_base_mcp/server.py:537-578 (handler)

  MCP tool handler function for list_notes. Processes input arguments, retrieves notes from storage, groups them by category, and returns a formatted text list.

  async def handle_list_notes(arguments: dict) -> list[TextContent]:
      """Handle list_notes tool call."""
      category_path = arguments.get("category_path")
      tag = arguments.get("tag")
      recursive = arguments.get("recursive", True)
  
      # Get notes
      notes = storage.list_notes(
          category_path=category_path,
          tag=tag,
          recursive=recursive
      )
  
      if not notes:
          return [TextContent(type="text", text="No notes found.")]
  
      # Group by category
      by_category = {}
      for note in notes:
          cat = note.category or 'root'
          if cat not in by_category:
              by_category[cat] = []
          by_category[cat].append(note)
  
      # Format output
      output_lines = []
  
      if category_path:
          recursive_str = " (including subcategories)" if recursive else " (non-recursive)"
          output_lines.append(f"Notes in {category_path}/{recursive_str} ({len(notes)} total):\n")
      else:
          output_lines.append(f"All notes ({len(notes)} total):\n")
  
      for cat in sorted(by_category.keys()):
          cat_notes = by_category[cat]
          output_lines.append(f"\n{cat}/ ({len(cat_notes)} notes):")
  
          for note in sorted(cat_notes, key=lambda n: n.title):
              tags_str = ', '.join(note.frontmatter.tags) if note.frontmatter.tags else 'no tags'
              output_lines.append(f"  - {note.title} [{tags_str}]")
  
      return [TextContent(type="text", text="\n".join(output_lines))]

• src/knowledge_base_mcp/server.py:242-262 (registration)

  Registration of the list_notes tool in the MCP server's list_tools() method, defining its name, description, and input schema.

      name="list_notes",
      description="List all notes, optionally filtered by category path or tag",
      inputSchema={
          "type": "object",
          "properties": {
              "category_path": {
                  "type": "string",
                  "description": "Optional category path filter (e.g., 'work/clients')",
              },
              "tag": {
                  "type": "string",
                  "description": "Optional tag filter",
              },
              "recursive": {
                  "type": "boolean",
                  "description": "If true, list notes in subcategories too (default: true)",
                  "default": True,
              },
          },
      },
  ),

• src/knowledge_base_mcp/server.py:244-261 (schema)

  Input schema/JSON Schema for the list_notes tool defining parameters: category_path, tag, recursive.

  inputSchema={
      "type": "object",
      "properties": {
          "category_path": {
              "type": "string",
              "description": "Optional category path filter (e.g., 'work/clients')",
          },
          "tag": {
              "type": "string",
              "description": "Optional tag filter",
          },
          "recursive": {
              "type": "boolean",
              "description": "If true, list notes in subcategories too (default: true)",
              "default": True,
          },
      },
  },

• src/knowledge_base_mcp/storage.py:724-776 (helper)

  Helper method in KnowledgeBaseStorage that implements the core listing logic: scans directories for .md files recursively or not, parses each into Note objects, filters by tag, skips invalid files.

  def list_notes(
      self,
      category_path: Optional[str] = None,
      tag: Optional[str] = None,
      recursive: bool = True
  ) -> list[Note]:
      """
      List all notes, optionally filtered by category path or tag.
  
      Args:
          category_path: Optional category path filter (e.g., "work/clients")
          tag: Optional tag filter
          recursive: If True, include notes from subcategories (default: True)
  
      Returns:
          List of Note objects
      """
      notes = []
  
      # Determine which path to search
      if category_path:
          normalized = normalize_path(category_path)
          search_path = self._get_category_path(normalized)
          if not search_path.exists():
              return []
      else:
          search_path = self.base_path
  
      # Find all markdown files
      if recursive:
          pattern = "**/*.md"
      else:
          pattern = "*.md"
  
      for file_path in search_path.glob(pattern):
          # Skip backup and temp files
          if file_path.suffix in ('.backup', '.tmp', '.deleted'):
              continue
  
          try:
              note = self._parse_note_file(file_path)
  
              # Apply tag filter if specified
              if tag and tag.lower() not in [t.lower() for t in note.frontmatter.tags]:
                  continue
  
              notes.append(note)
  
          except StorageError:
              # Skip files that can't be parsed
              continue
  
      return notes