okb 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

okb/mcp_server.py

@@ -4,14 +4,14 @@ MCP Server for Knowledge Base.
 Exposes semantic search to Claude Code via the Model Context Protocol.
 
 Usage:
-    python mcp_server.py
+    okb serve
 
-Configure in Claude Code (~/.claude.json or similar):
+Configure in Claude Code (see https://docs.anthropic.com/en/docs/claude-code):
     {
       "mcpServers": {
         "knowledge-base": {
-          "command": "python",
-          "args": ["/path/to/mcp_server.py"]
+          "command": "okb",
+          "args": ["serve"]
         }
       }
     }
@@ -313,6 +313,69 @@ class KnowledgeBase:
         """).fetchall()
         return [r["project"] for r in results]
 
+    def get_project_stats(self) -> list[dict]:
+        """Get projects with document counts for consolidation review."""
+        conn = self.get_connection()
+        results = conn.execute("""
+            SELECT
+                metadata->>'project' as project,
+                COUNT(*) as doc_count,
+                array_agg(DISTINCT source_type) as source_types
+            FROM documents
+            WHERE metadata->>'project' IS NOT NULL
+            GROUP BY metadata->>'project'
+            ORDER BY doc_count DESC, project
+        """).fetchall()
+        return [dict(r) for r in results]
+
+    def list_documents_by_project(self, project: str, limit: int = 100) -> list[dict]:
+        """List documents for a specific project."""
+        conn = self.get_connection()
+        rows = conn.execute(
+            """SELECT source_path, title, source_type FROM documents
+               WHERE metadata->>'project' = %s ORDER BY title LIMIT %s""",
+            (project, limit),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def rename_project(self, old_name: str, new_name: str) -> int:
+        """Rename a project (update all documents). Returns count of updated docs."""
+        conn = self.get_connection()
+        result = conn.execute(
+            """
+            UPDATE documents
+            SET metadata = jsonb_set(metadata, '{project}', %s::jsonb)
+            WHERE metadata->>'project' = %s
+            """,
+            (f'"{new_name}"', old_name),
+        )
+        conn.commit()
+        return result.rowcount
+
+    def set_document_project(self, source_path: str, project: str | None) -> bool:
+        """Set or clear the project for a single document."""
+        conn = self.get_connection()
+        if project:
+            result = conn.execute(
+                """
+                UPDATE documents
+                SET metadata = jsonb_set(metadata, '{project}', %s::jsonb)
+                WHERE source_path = %s
+                """,
+                (f'"{project}"', source_path),
+            )
+        else:
+            result = conn.execute(
+                """
+                UPDATE documents
+                SET metadata = metadata - 'project'
+                WHERE source_path = %s
+                """,
+                (source_path,),
+            )
+        conn.commit()
+        return result.rowcount > 0
+
     def get_document(self, source_path: str) -> dict | None:
         """Get full document content by path."""
         conn = self.get_connection()
@@ -435,10 +498,7 @@ class KnowledgeBase:
         }
 
     def delete_knowledge(self, source_path: str) -> bool:
-        """Delete a Claude-saved knowledge entry by source path."""
-        if not source_path.startswith("claude://"):
-            return False
-
+        """Delete a document by source path."""
         conn = self.get_connection()
         result = conn.execute(
             "DELETE FROM documents WHERE source_path = %s RETURNING id",
@@ -676,6 +736,571 @@ class KnowledgeBase:
         return [dict(r) for r in results]
 
 
+def _get_sync_state(conn, source_name: str, db_name: str):
+    """Get sync state from database."""
+    from .plugins.base import SyncState
+
+    result = conn.execute(
+        """SELECT last_sync, cursor, extra FROM sync_state
+           WHERE source_name = %s AND database_name = %s""",
+        (source_name, db_name),
+    ).fetchone()
+
+    if result:
+        return SyncState(
+            last_sync=result["last_sync"],
+            cursor=result["cursor"],
+            extra=result["extra"] or {},
+        )
+    return None
+
+
+def _save_sync_state(conn, source_name: str, db_name: str, state):
+    """Save sync state to database."""
+    import json
+
+    conn.execute(
+        """INSERT INTO sync_state (source_name, database_name, last_sync, cursor, extra, updated_at)
+           VALUES (%s, %s, %s, %s, %s, NOW())
+           ON CONFLICT (source_name, database_name)
+           DO UPDATE SET last_sync = EXCLUDED.last_sync,
+                        cursor = EXCLUDED.cursor,
+                        extra = EXCLUDED.extra,
+                        updated_at = NOW()""",
+        (source_name, db_name, state.last_sync, state.cursor, json.dumps(state.extra)),
+    )
+    conn.commit()
+
+
+def _run_sync(
+    db_url: str,
+    sources: list[str],
+    sync_all: bool = False,
+    full: bool = False,
+    doc_ids: list[str] | None = None,
+) -> str:
+    """Run sync for specified sources and return formatted result."""
+    from psycopg.rows import dict_row
+
+    from .ingest import Ingester
+    from .plugins.registry import PluginRegistry
+
+    # Determine which sources to sync
+    if sync_all:
+        source_names = config.list_enabled_sources()
+    elif sources:
+        source_names = list(sources)
+    else:
+        # Return list of available sources
+        installed = PluginRegistry.list_sources()
+        configured = config.list_enabled_sources()
+        lines = ["Available API sources:"]
+        for name in installed:
+            status = "enabled" if name in configured else "disabled"
+            lines.append(f"  - {name} ({status})")
+        if not installed:
+            lines.append("  (none installed)")
+        return "\n".join(lines)
+
+    if not source_names:
+        return "No sources to sync."
+
+    # Get database name from URL for sync state
+    db_name = config.get_database().name
+
+    results = []
+    ingester = Ingester(db_url, use_modal=True)
+
+    with psycopg.connect(db_url, row_factory=dict_row) as conn:
+        for source_name in source_names:
+            # Get the plugin
+            source = PluginRegistry.get_source(source_name)
+            if source is None:
+                results.append(f"{source_name}: not found")
+                continue
+
+            # Get and resolve config
+            source_cfg = config.get_source_config(source_name)
+            if source_cfg is None:
+                results.append(f"{source_name}: not configured or disabled")
+                continue
+
+            # Inject doc_ids if provided (for sources that support it)
+            if doc_ids:
+                source_cfg = {**source_cfg, "doc_ids": doc_ids}
+
+            try:
+                source.configure(source_cfg)
+            except Exception as e:
+                results.append(f"{source_name}: config error - {e}")
+                continue
+
+            # Get sync state (unless full)
+            state = None if full else _get_sync_state(conn, source_name, db_name)
+
+            try:
+                documents, new_state = source.fetch(state)
+            except Exception as e:
+                results.append(f"{source_name}: fetch error - {e}")
+                continue
+
+            if documents:
+                ingester.ingest_documents(documents)
+                results.append(f"{source_name}: synced {len(documents)} documents")
+            else:
+                results.append(f"{source_name}: no new documents")
+
+            # Save state
+            _save_sync_state(conn, source_name, db_name, new_state)
+
+    return "\n".join(results)
+
+
+def _run_rescan(
+    db_url: str,
+    dry_run: bool = False,
+    delete_missing: bool = False,
+) -> str:
+    """Run rescan and return formatted result."""
+    from .rescan import Rescanner
+
+    rescanner = Rescanner(db_url, use_modal=True)
+    result = rescanner.rescan(dry_run=dry_run, delete_missing=delete_missing, verbose=False)
+
+    lines = []
+    if dry_run:
+        lines.append("(dry run - no changes made)")
+
+    if result.updated:
+        lines.append(f"Updated: {len(result.updated)} files")
+        for path in result.updated[:5]:  # Show first 5
+            lines.append(f"  - {path}")
+        if len(result.updated) > 5:
+            lines.append(f"  ... and {len(result.updated) - 5} more")
+
+    if result.deleted:
+        lines.append(f"Deleted: {len(result.deleted)} files")
+
+    if result.missing:
+        lines.append(f"Missing (not deleted): {len(result.missing)} files")
+        for path in result.missing[:5]:
+            lines.append(f"  - {path}")
+        if len(result.missing) > 5:
+            lines.append(f"  ... and {len(result.missing) - 5} more")
+
+    lines.append(f"Unchanged: {result.unchanged} files")
+
+    if result.errors:
+        lines.append(f"Errors: {len(result.errors)}")
+        for path, error in result.errors[:3]:
+            lines.append(f"  - {path}: {error}")
+        if len(result.errors) > 3:
+            lines.append(f"  ... and {len(result.errors) - 3} more")
+
+    return "\n".join(lines) if lines else "No indexed files found."
+
+
+def _list_sync_sources(db_url: str, db_name: str) -> str:
+    """List available sync sources with status and last sync time."""
+    import psycopg
+    from psycopg.rows import dict_row
+
+    from .plugins.registry import PluginRegistry
+
+    installed = PluginRegistry.list_sources()
+    enabled = set(config.list_enabled_sources())
+
+    if not installed:
+        return "No API sync sources installed."
+
+    # Get last sync times from database
+    last_syncs = {}
+    try:
+        with psycopg.connect(db_url, row_factory=dict_row) as conn:
+            results = conn.execute(
+                """SELECT source_name, last_sync FROM sync_state WHERE database_name = %s""",
+                (db_name,),
+            ).fetchall()
+            last_syncs = {r["source_name"]: r["last_sync"] for r in results}
+    except Exception:
+        pass  # Database may not be accessible
+
+    lines = ["## API Sync Sources\n"]
+
+    for name in sorted(installed):
+        source = PluginRegistry.get_source(name)
+        status = "enabled" if name in enabled else "disabled"
+        source_type = source.source_type if source else "unknown"
+
+        last_sync = last_syncs.get(name)
+        if last_sync:
+            last_sync_str = format_relative_time(last_sync.isoformat())
+        else:
+            last_sync_str = "never"
+
+        lines.append(f"- **{name}** ({status}) - {source_type}")
+        lines.append(f"  Last sync: {last_sync_str}")
+
+    return "\n".join(lines)
+
+
+def _enrich_document(
+    db_url: str,
+    source_path: str,
+    extract_todos: bool = True,
+    extract_entities: bool = True,
+    auto_create_entities: bool = False,
+    use_modal: bool = True,
+) -> str:
+    """Run enrichment on a specific document."""
+    from psycopg.rows import dict_row
+
+    from .llm import get_llm
+    from .llm.enrich import EnrichmentConfig, process_enrichment
+
+    # Check LLM is configured
+    if get_llm() is None:
+        return (
+            "Error: No LLM provider configured. "
+            "Enrichment requires an LLM. Set ANTHROPIC_API_KEY or configure llm.provider in config."
+        )
+
+    with psycopg.connect(db_url, row_factory=dict_row) as conn:
+        doc = conn.execute(
+            "SELECT id, source_path, title, content, source_type, metadata FROM documents WHERE source_path = %s",
+            (source_path,),
+        ).fetchone()
+
+        if not doc:
+            return f"Document not found: {source_path}"
+
+        enrich_config = EnrichmentConfig(
+            extract_todos=extract_todos,
+            extract_entities=extract_entities,
+            auto_create_todos=True,
+            auto_create_entities=auto_create_entities,
+        )
+
+        project = doc["metadata"].get("project") if doc["metadata"] else None
+
+        stats = process_enrichment(
+            document_id=str(doc["id"]),
+            source_path=doc["source_path"],
+            title=doc["title"],
+            content=doc["content"],
+            source_type=doc["source_type"],
+            db_url=db_url,
+            config=enrich_config,
+            project=project,
+            use_modal=use_modal,
+        )
+
+    lines = [f"Enriched: {source_path}"]
+    if stats["todos_created"]:
+        lines.append(f"  TODOs created: {stats['todos_created']}")
+    if stats["entities_pending"]:
+        lines.append(f"  Entities pending review: {stats['entities_pending']}")
+    if stats["entities_created"]:
+        lines.append(f"  Entities created: {stats['entities_created']}")
+    if not any(stats.values()):
+        lines.append("  No TODOs or entities extracted")
+
+    return "\n".join(lines)
+
+
+def _list_pending_entities(
+    db_url: str,
+    entity_type: str | None = None,
+    limit: int = 20,
+) -> str:
+    """List pending entity suggestions."""
+    from .llm.enrich import list_pending_entities
+
+    entities = list_pending_entities(db_url, entity_type=entity_type, limit=limit)
+
+    if not entities:
+        return "No pending entity suggestions."
+
+    lines = ["## Pending Entities\n"]
+    for e in entities:
+        confidence = e.get("confidence", 0)
+        confidence_str = f" ({confidence:.0%})" if confidence else ""
+        lines.append(f"- **{e['entity_name']}** ({e['entity_type']}){confidence_str}")
+        lines.append(f"  ID: `{e['id']}`")
+        if e.get("description"):
+            lines.append(f"  {e['description']}")
+        if e.get("aliases"):
+            lines.append(f"  Aliases: {', '.join(e['aliases'])}")
+        lines.append(f"  Source: {e['source_title']}")
+        lines.append("")
+
+    lines.append(f"\nUse `approve_entity` or `reject_entity` with the entity ID.")
+    return "\n".join(lines)
+
+
+def _approve_entity(
+    db_url: str, pending_id: str, use_modal: bool = True, run_async: bool = False
+) -> str:
+    """Approve a pending entity.
+
+    Args:
+        db_url: Database URL
+        pending_id: ID of the pending entity
+        use_modal: If True, use Modal GPU for embedding; else local CPU
+        run_async: If True, return immediately while embedding happens in background
+    """
+    from .llm.enrich import approve_entity, approve_entity_async
+
+    if run_async:
+        future = approve_entity_async(db_url, pending_id, use_modal)
+        # Return immediately - don't wait for completion
+        return (
+            f"Entity approval queued (ID: {pending_id}). "
+            "Embedding is being generated in the background. "
+            "The entity will be searchable once complete."
+        )
+
+    source_path = approve_entity(db_url, pending_id, use_modal)
+    if source_path:
+        return f"Entity approved and created: `{source_path}`"
+    return "Failed to approve entity. ID may be invalid or already processed."
+
+
+def _reject_entity(db_url: str, pending_id: str) -> str:
+    """Reject a pending entity."""
+    from .llm.enrich import reject_entity
+
+    if reject_entity(db_url, pending_id):
+        return "Entity rejected."
+    return "Failed to reject entity. ID may be invalid or already processed."
+
+
+def _analyze_knowledge_base(
+    db_url: str,
+    project: str | None = None,
+    sample_size: int = 15,
+    auto_update: bool = True,
+) -> str:
+    """Analyze the knowledge base and return formatted result."""
+    from .llm import get_llm
+    from .llm.analyze import analyze_database, format_analysis_result
+
+    # Check LLM is configured
+    if get_llm() is None:
+        return (
+            "Error: No LLM provider configured. "
+            "Analysis requires an LLM. Set ANTHROPIC_API_KEY or configure llm.provider in config."
+        )
+
+    try:
+        result = analyze_database(
+            db_url=db_url,
+            project=project,
+            sample_size=sample_size,
+            auto_update=auto_update,
+        )
+        return format_analysis_result(result)
+    except Exception as e:
+        return f"Error analyzing knowledge base: {e}"
+
+
+def _find_entity_duplicates(
+    db_url: str,
+    similarity_threshold: float = 0.85,
+    entity_type: str | None = None,
+    use_llm: bool = True,
+) -> str:
+    """Find duplicate entities and return formatted result."""
+    from .llm.extractors.dedup import create_pending_merge, find_duplicate_entities
+
+    pairs = find_duplicate_entities(
+        db_url,
+        similarity_threshold=similarity_threshold,
+        use_llm=use_llm,
+        entity_type=entity_type,
+    )
+
+    if not pairs:
+        return "No potential duplicate entities found."
+
+    lines = ["## Potential Duplicate Entities\n"]
+    for p in pairs:
+        lines.append(f"- **{p.canonical_name}** ↔ **{p.duplicate_name}**")
+        lines.append(f"  Confidence: {p.confidence:.0%} ({p.reason})")
+        lines.append(f"  Types: {p.canonical_type} / {p.duplicate_type}")
+
+        # Create pending merge
+        merge_id = create_pending_merge(db_url, p)
+        if merge_id:
+            lines.append(f"  Pending merge ID: `{merge_id}`")
+        lines.append("")
+
+    lines.append(f"\nFound {len(pairs)} potential duplicates.")
+    lines.append("Use `approve_merge` or `reject_merge` with merge IDs to process.")
+    return "\n".join(lines)
+
+
+def _merge_entities(db_url: str, canonical_path: str, duplicate_path: str) -> str:
+    """Merge two entities and return result."""
+    from psycopg.rows import dict_row
+
+    from .llm.extractors.dedup import execute_merge
+
+    with psycopg.connect(db_url, row_factory=dict_row) as conn:
+        # Get entity IDs from paths
+        canonical = conn.execute(
+            "SELECT id, title FROM documents WHERE source_path = %s AND source_type = 'entity'",
+            (canonical_path,),
+        ).fetchone()
+        duplicate = conn.execute(
+            "SELECT id, title FROM documents WHERE source_path = %s AND source_type = 'entity'",
+            (duplicate_path,),
+        ).fetchone()
+
+        if not canonical:
+            return f"Error: Canonical entity not found: {canonical_path}"
+        if not duplicate:
+            return f"Error: Duplicate entity not found: {duplicate_path}"
+
+        if execute_merge(db_url, str(canonical["id"]), str(duplicate["id"])):
+            return (
+                f"Merge successful:\n"
+                f"- Kept: {canonical['title']} ({canonical_path})\n"
+                f"- Merged: {duplicate['title']} (deleted, added as alias)"
+            )
+        return "Error: Merge failed."
+
+
+def _list_pending_merges(db_url: str, limit: int = 50) -> str:
+    """List pending entity merges."""
+    from .llm.extractors.dedup import list_pending_merges
+
+    merges = list_pending_merges(db_url, limit=limit)
+
+    if not merges:
+        return "No pending entity merges."
+
+    lines = ["## Pending Entity Merges\n"]
+    for m in merges:
+        lines.append(f"- **{m['canonical_name']}** ← {m['duplicate_name']}")
+        lines.append(f"  ID: `{m['id']}`")
+        lines.append(f"  Confidence: {m['confidence']:.0%} ({m['reason']})")
+        lines.append("")
+
+    lines.append(f"\n{len(merges)} pending merges.")
+    lines.append("Use `approve_merge` or `reject_merge` with IDs to process.")
+    return "\n".join(lines)
+
+
+def _approve_merge(db_url: str, merge_id: str) -> str:
+    """Approve and execute a pending merge."""
+    from .llm.extractors.dedup import approve_merge
+
+    if approve_merge(db_url, merge_id):
+        return "Merge approved and executed."
+    return "Error: Failed to approve merge. ID may be invalid or already processed."
+
+
+def _reject_merge(db_url: str, merge_id: str) -> str:
+    """Reject a pending merge."""
+    from .llm.extractors.dedup import reject_merge
+
+    if reject_merge(db_url, merge_id):
+        return "Merge rejected."
+    return "Error: Failed to reject merge. ID may be invalid or already processed."
+
+
+def _get_topic_clusters(db_url: str, limit: int = 20) -> str:
+    """Get topic clusters."""
+    from .llm.consolidate import get_topic_clusters
+
+    clusters = get_topic_clusters(db_url, limit=limit)
+
+    if not clusters:
+        return "No topic clusters found. Run `run_consolidation` to create clusters."
+
+    lines = ["## Topic Clusters\n"]
+    for c in clusters:
+        lines.append(f"### {c['name']}")
+        if c.get("description"):
+            lines.append(c["description"])
+        lines.append(f"Members: {c['member_count']}")
+
+        # Show top members
+        entities = [m for m in c.get("members", []) if m.get("is_entity")]
+        if entities:
+            entity_names = [m["title"] for m in entities[:5]]
+            lines.append(f"Entities: {', '.join(entity_names)}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _get_entity_relationships(
+    db_url: str,
+    entity_name: str | None = None,
+    relationship_type: str | None = None,
+    limit: int = 50,
+) -> str:
+    """Get entity relationships."""
+    from .llm.consolidate import get_entity_relationships
+
+    relationships = get_entity_relationships(
+        db_url, entity_name=entity_name, relationship_type=relationship_type, limit=limit
+    )
+
+    if not relationships:
+        if entity_name:
+            return f"No relationships found involving '{entity_name}'."
+        return "No entity relationships found. Run `run_consolidation` to extract relationships."
+
+    lines = ["## Entity Relationships\n"]
+    for r in relationships:
+        source = r["source"]["name"]
+        target = r["target"]["name"]
+        rel_type = r["type"]
+        confidence = r.get("confidence", 0)
+
+        lines.append(f"- **{source}** → *{rel_type}* → **{target}** ({confidence:.0%})")
+        if r.get("context"):
+            lines.append(f"  {r['context']}")
+
+    return "\n".join(lines)
+
+
+def _run_consolidation(
+    db_url: str,
+    detect_duplicates: bool = True,
+    detect_cross_doc: bool = True,
+    build_clusters: bool = True,
+    extract_relationships: bool = True,
+    dry_run: bool = False,
+) -> str:
+    """Run consolidation pipeline."""
+    from .llm import get_llm
+    from .llm.consolidate import format_consolidation_result, run_consolidation
+
+    # Check LLM is configured (needed for several phases)
+    if get_llm() is None and (detect_cross_doc or build_clusters or extract_relationships):
+        return (
+            "Error: No LLM provider configured. "
+            "Consolidation requires an LLM for cross-doc detection, clustering, and relationships. "
+            "Set ANTHROPIC_API_KEY or configure llm.provider in config."
+        )
+
+    result = run_consolidation(
+        db_url,
+        detect_duplicates=detect_duplicates,
+        detect_cross_doc=detect_cross_doc,
+        build_clusters=build_clusters,
+        extract_relationships=extract_relationships,
+        auto_merge_threshold=config.consolidation_auto_merge_threshold,
+        dry_run=dry_run,
+    )
+
+    return format_consolidation_result(result)
+
+
 def build_server_instructions(db_config) -> str | None:
     """Build server instructions from database config and LLM metadata."""
     parts = []
@@ -828,6 +1453,78 @@ async def list_tools() -> list[Tool]:
                 "properties": {},
             },
         ),
+        Tool(
+            name="get_project_stats",
+            description=(
+                "Get projects with document counts. Use this to identify projects that should "
+                "be consolidated (similar names, typos, etc.)."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            },
+        ),
+        Tool(
+            name="list_documents_by_project",
+            description="List all documents belonging to a specific project.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "project": {
+                        "type": "string",
+                        "description": "Project name to list documents for",
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum documents to return (default: 100)",
+                        "default": 100,
+                    },
+                },
+                "required": ["project"],
+            },
+        ),
+        Tool(
+            name="rename_project",
+            description=(
+                "Rename a project, updating all documents. Use for consolidating similar "
+                "project names (e.g., 'my-app' and 'MyApp' -> 'my-app'). Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "old_name": {
+                        "type": "string",
+                        "description": "Current project name to rename",
+                    },
+                    "new_name": {
+                        "type": "string",
+                        "description": "New project name",
+                    },
+                },
+                "required": ["old_name", "new_name"],
+            },
+        ),
+        Tool(
+            name="set_document_project",
+            description=(
+                "Set or clear the project for a single document. Use to fix incorrectly "
+                "categorized documents. Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "source_path": {
+                        "type": "string",
+                        "description": "Path of the document to update",
+                    },
+                    "project": {
+                        "type": "string",
+                        "description": "New project name (omit or null to clear project)",
+                    },
+                },
+                "required": ["source_path"],
+            },
+        ),
         Tool(
             name="recent_documents",
             description="Get recently indexed or updated documents.",
@@ -877,8 +1574,8 @@ async def list_tools() -> list[Tool]:
         Tool(
             name="delete_knowledge",
             description=(
-                "Delete a previously saved knowledge entry by its source path. "
-                "Only works for Claude-saved entries (claude:// paths)."
+                "Delete a document from the knowledge base by its source path. "
+                "Works for any document type. Requires write permission."
             ),
             inputSchema={
                 "type": "object",
@@ -1025,6 +1722,396 @@ async def list_tools() -> list[Tool]:
                 "required": ["title"],
             },
         ),
+        Tool(
+            name="trigger_sync",
+            description=(
+                "Trigger sync of API sources (Todoist, GitHub, Dropbox Paper, etc.). "
+                "Fetches new/updated content from external services. Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "sources": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": (
+                            "List of source names to sync (e.g., ['todoist', 'github']). "
+                            "If empty and 'all' is false, returns list of available sources."
+                        ),
+                    },
+                    "all": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Sync all enabled sources",
+                    },
+                    "full": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Ignore incremental state and do full resync",
+                    },
+                    "doc_ids": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": (
+                            "Specific document IDs to sync (for dropbox-paper). "
+                            "If provided, only these documents are synced."
+                        ),
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="trigger_rescan",
+            description=(
+                "Check indexed files for changes and re-ingest stale ones. "
+                "Compares stored modification times with current filesystem. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "dry_run": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Only report what would change, don't actually re-ingest",
+                    },
+                    "delete_missing": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Remove documents for files that no longer exist",
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="list_sync_sources",
+            description=(
+                "List available API sync sources (Todoist, GitHub, Dropbox Paper, etc.) "
+                "with their enabled/disabled status and last sync time. "
+                "Use this to see what external data sources can be synced."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            },
+        ),
+        Tool(
+            name="enrich_document",
+            description=(
+                "Run LLM enrichment on a document to extract TODOs and entities. "
+                "TODOs are created as separate documents, entities go to pending review. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "source_path": {
+                        "type": "string",
+                        "description": "Path of the document to enrich",
+                    },
+                    "extract_todos": {
+                        "type": "boolean",
+                        "default": True,
+                        "description": "Whether to extract TODOs",
+                    },
+                    "extract_entities": {
+                        "type": "boolean",
+                        "default": True,
+                        "description": "Whether to extract entities",
+                    },
+                    "auto_create_entities": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Auto-create entities instead of pending review",
+                    },
+                    "use_local": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Use local CPU embedding instead of Modal GPU",
+                    },
+                },
+                "required": ["source_path"],
+            },
+        ),
+        Tool(
+            name="list_pending_entities",
+            description=(
+                "List entity suggestions awaiting review. "
+                "Entities are extracted from documents but need approval before becoming searchable. "
+                "Use approve_entity or reject_entity to process them."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "entity_type": {
+                        "type": "string",
+                        "enum": ["person", "project", "technology", "concept", "organization"],
+                        "description": "Filter by entity type (optional)",
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "default": 20,
+                        "description": "Maximum results",
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="approve_entity",
+            description=(
+                "Approve a pending entity, creating it as a searchable document. "
+                "The entity will be linked to its source document(s). "
+                "Use async=true to return immediately while embedding runs in background. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "pending_id": {
+                        "type": "string",
+                        "description": "ID of the pending entity to approve",
+                    },
+                    "async": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": (
+                            "If true, return immediately while embedding runs in background. "
+                            "Useful to avoid blocking when approving multiple entities."
+                        ),
+                    },
+                    "use_local": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Use local CPU embedding instead of Modal GPU",
+                    },
+                },
+                "required": ["pending_id"],
+            },
+        ),
+        Tool(
+            name="reject_entity",
+            description=(
+                "Reject a pending entity suggestion. "
+                "The entity will be marked as rejected and not shown again. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "pending_id": {
+                        "type": "string",
+                        "description": "ID of the pending entity to reject",
+                    },
+                },
+                "required": ["pending_id"],
+            },
+        ),
+        Tool(
+            name="analyze_knowledge_base",
+            description=(
+                "Analyze the knowledge base to generate or update its description and topics. "
+                "Uses entity data and document samples to understand themes and content. "
+                "Results are stored in database_metadata for future sessions. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "project": {
+                        "type": "string",
+                        "description": "Analyze only a specific project (optional)",
+                    },
+                    "sample_size": {
+                        "type": "integer",
+                        "description": "Number of documents to sample (default: 15)",
+                        "default": 15,
+                    },
+                    "auto_update": {
+                        "type": "boolean",
+                        "description": "Update database metadata with results (default: true)",
+                        "default": True,
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="find_entity_duplicates",
+            description=(
+                "Scan for potential duplicate entities using embedding similarity and LLM. "
+                "Returns pairs of entities that may refer to the same thing. "
+                "Use merge_entities or list_pending_merges to act on results."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "similarity_threshold": {
+                        "type": "number",
+                        "description": "Minimum similarity to consider duplicates (default: 0.85)",
+                        "default": 0.85,
+                    },
+                    "entity_type": {
+                        "type": "string",
+                        "enum": ["person", "project", "technology", "concept", "organization"],
+                        "description": "Filter to specific entity type (optional)",
+                    },
+                    "use_llm": {
+                        "type": "boolean",
+                        "description": "Use LLM for batch duplicate detection (default: true)",
+                        "default": True,
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="merge_entities",
+            description=(
+                "Merge two entities: redirect refs from duplicate to canonical, "
+                "add duplicate's name as alias, delete duplicate. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "canonical_path": {
+                        "type": "string",
+                        "description": "Source path of the entity to keep",
+                    },
+                    "duplicate_path": {
+                        "type": "string",
+                        "description": "Source path of the entity to merge into canonical",
+                    },
+                },
+                "required": ["canonical_path", "duplicate_path"],
+            },
+        ),
+        Tool(
+            name="list_pending_merges",
+            description=(
+                "List pending entity merge proposals awaiting approval. "
+                "Created by find_entity_duplicates or run_consolidation."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum results (default: 50)",
+                        "default": 50,
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="approve_merge",
+            description=(
+                "Approve a pending entity merge. Executes the merge: "
+                "redirects refs, adds alias, deletes duplicate. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "merge_id": {
+                        "type": "string",
+                        "description": "ID of the pending merge to approve",
+                    },
+                },
+                "required": ["merge_id"],
+            },
+        ),
+        Tool(
+            name="reject_merge",
+            description=(
+                "Reject a pending entity merge proposal. "
+                "Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "merge_id": {
+                        "type": "string",
+                        "description": "ID of the pending merge to reject",
+                    },
+                },
+                "required": ["merge_id"],
+            },
+        ),
+        Tool(
+            name="get_topic_clusters",
+            description=(
+                "Get topic clusters - groups of related entities and documents. "
+                "Clusters are created by run_consolidation."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum clusters to return (default: 20)",
+                        "default": 20,
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="get_entity_relationships",
+            description=(
+                "Get relationships between entities (works_for, uses, belongs_to, related_to). "
+                "Relationships are extracted by run_consolidation."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "entity_name": {
+                        "type": "string",
+                        "description": "Filter to relationships involving this entity (optional)",
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum results (default: 50)",
+                        "default": 50,
+                    },
+                },
+            },
+        ),
+        Tool(
+            name="run_consolidation",
+            description=(
+                "Run full entity consolidation pipeline: duplicate detection, "
+                "cross-document entity detection, topic clustering, relationship extraction. "
+                "Creates pending proposals for review. Requires write permission."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "detect_duplicates": {
+                        "type": "boolean",
+                        "description": "Run duplicate entity detection (default: true)",
+                        "default": True,
+                    },
+                    "detect_cross_doc": {
+                        "type": "boolean",
+                        "description": "Run cross-document entity detection (default: true)",
+                        "default": True,
+                    },
+                    "build_clusters": {
+                        "type": "boolean",
+                        "description": "Build topic clusters (default: true)",
+                        "default": True,
+                    },
+                    "extract_relationships": {
+                        "type": "boolean",
+                        "description": "Extract entity relationships (default: true)",
+                        "default": True,
+                    },
+                    "dry_run": {
+                        "type": "boolean",
+                        "description": "Report what would happen without making changes",
+                        "default": False,
+                    },
+                },
+            },
+        ),
     ]
 
 
@@ -1187,6 +2274,63 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> CallToolResult:
                 ]
             )
 
+        elif name == "get_project_stats":
+            stats = kb.get_project_stats()
+            if not stats:
+                return CallToolResult(content=[TextContent(type="text", text="No projects found.")])
+            output = ["## Project Statistics\n"]
+            output.append("| Project | Documents | Source Types |")
+            output.append("|---------|-----------|--------------|")
+            for s in stats:
+                types = ", ".join(s["source_types"]) if s["source_types"] else "-"
+                output.append(f"| {s['project']} | {s['doc_count']} | {types} |")
+            return CallToolResult(content=[TextContent(type="text", text="\n".join(output))])
+
+        elif name == "list_documents_by_project":
+            project = arguments["project"]
+            limit = arguments.get("limit", 100)
+            docs = kb.list_documents_by_project(project, limit)
+            if not docs:
+                msg = f"No documents found for project '{project}'."
+                return CallToolResult(content=[TextContent(type="text", text=msg)])
+            output = [f"## Documents in '{project}' ({len(docs)} documents)\n"]
+            for d in docs:
+                output.append(f"- **{d['title'] or d['source_path']}** ({d['source_type']})")
+                output.append(f"  - `{d['source_path']}`")
+            return CallToolResult(content=[TextContent(type="text", text="\n".join(output))])
+
+        elif name == "rename_project":
+            old_name = arguments["old_name"]
+            new_name = arguments["new_name"]
+            if old_name == new_name:
+                return CallToolResult(
+                    content=[TextContent(type="text", text="Old and new names are the same.")]
+                )
+            count = kb.rename_project(old_name, new_name)
+            if count == 0:
+                return CallToolResult(
+                    content=[TextContent(type="text", text=f"No documents found with project '{old_name}'.")]
+                )
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"Renamed project '{old_name}' to '{new_name}' ({count} documents updated).")]
+            )
+
+        elif name == "set_document_project":
+            source_path = arguments["source_path"]
+            project = arguments.get("project")
+            success = kb.set_document_project(source_path, project)
+            if not success:
+                return CallToolResult(
+                    content=[TextContent(type="text", text=f"Document not found: {source_path}")]
+                )
+            if project:
+                return CallToolResult(
+                    content=[TextContent(type="text", text=f"Set project to '{project}' for {source_path}")]
+                )
+            return CallToolResult(
+                content=[TextContent(type="text", text=f"Cleared project for {source_path}")]
+            )
+
         elif name == "recent_documents":
             docs = kb.get_recent_documents(arguments.get("limit", 10))
             if not docs:
@@ -1242,13 +2386,13 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> CallToolResult:
             deleted = kb.delete_knowledge(arguments["source_path"])
             if deleted:
                 return CallToolResult(
-                    content=[TextContent(type="text", text="Knowledge entry deleted.")]
+                    content=[TextContent(type="text", text="Document deleted.")]
                 )
             return CallToolResult(
                 content=[
                     TextContent(
                         type="text",
-                        text="Could not delete. Entry not found or not a Claude-saved entry.",
+                        text="Could not delete. Document not found.",
                     )
                 ]
             )
@@ -1358,6 +2502,129 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> CallToolResult:
                 parts.append(f"- Due: {result['due_date']}")
             return CallToolResult(content=[TextContent(type="text", text="\n".join(parts))])
 
+        elif name == "trigger_sync":
+            result = _run_sync(
+                kb.db_url,
+                sources=arguments.get("sources", []),
+                sync_all=arguments.get("all", False),
+                full=arguments.get("full", False),
+                doc_ids=arguments.get("doc_ids"),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "trigger_rescan":
+            result = _run_rescan(
+                kb.db_url,
+                dry_run=arguments.get("dry_run", False),
+                delete_missing=arguments.get("delete_missing", False),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "list_sync_sources":
+            db_name = config.get_database().name
+            result = _list_sync_sources(kb.db_url, db_name)
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "enrich_document":
+            result = _enrich_document(
+                kb.db_url,
+                source_path=arguments["source_path"],
+                extract_todos=arguments.get("extract_todos", True),
+                extract_entities=arguments.get("extract_entities", True),
+                auto_create_entities=arguments.get("auto_create_entities", False),
+                use_modal=not arguments.get("use_local", False),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "list_pending_entities":
+            result = _list_pending_entities(
+                kb.db_url,
+                entity_type=arguments.get("entity_type"),
+                limit=arguments.get("limit", 20),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "approve_entity":
+            result = _approve_entity(
+                kb.db_url,
+                arguments["pending_id"],
+                use_modal=not arguments.get("use_local", False),
+                run_async=arguments.get("async", False),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "reject_entity":
+            result = _reject_entity(kb.db_url, arguments["pending_id"])
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "analyze_knowledge_base":
+            result = _analyze_knowledge_base(
+                kb.db_url,
+                project=arguments.get("project"),
+                sample_size=arguments.get("sample_size", 15),
+                auto_update=arguments.get("auto_update", True),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "find_entity_duplicates":
+            result = _find_entity_duplicates(
+                kb.db_url,
+                similarity_threshold=arguments.get("similarity_threshold", 0.85),
+                entity_type=arguments.get("entity_type"),
+                use_llm=arguments.get("use_llm", True),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "merge_entities":
+            result = _merge_entities(
+                kb.db_url,
+                canonical_path=arguments["canonical_path"],
+                duplicate_path=arguments["duplicate_path"],
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "list_pending_merges":
+            result = _list_pending_merges(
+                kb.db_url,
+                limit=arguments.get("limit", 50),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "approve_merge":
+            result = _approve_merge(kb.db_url, arguments["merge_id"])
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "reject_merge":
+            result = _reject_merge(kb.db_url, arguments["merge_id"])
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "get_topic_clusters":
+            result = _get_topic_clusters(
+                kb.db_url,
+                limit=arguments.get("limit", 20),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "get_entity_relationships":
+            result = _get_entity_relationships(
+                kb.db_url,
+                entity_name=arguments.get("entity_name"),
+                relationship_type=arguments.get("relationship_type"),
+                limit=arguments.get("limit", 50),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
+        elif name == "run_consolidation":
+            result = _run_consolidation(
+                kb.db_url,
+                detect_duplicates=arguments.get("detect_duplicates", True),
+                detect_cross_doc=arguments.get("detect_cross_doc", True),
+                build_clusters=arguments.get("build_clusters", True),
+                extract_relationships=arguments.get("extract_relationships", True),
+                dry_run=arguments.get("dry_run", False),
+            )
+            return CallToolResult(content=[TextContent(type="text", text=result)])
+
         else:
             return CallToolResult(content=[TextContent(type="text", text=f"Unknown tool: {name}")])