nia-mcp-server 1.0.22__tar.gz → 1.0.24__tar.gz

{nia_mcp_server-1.0.22 → nia_mcp_server-1.0.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nia-mcp-server
-Version: 1.0.22
+Version: 1.0.24
 Summary: Nia Knowledge Agent
 Project-URL: Homepage, https://trynia.ai
 Project-URL: Documentation, https://docs.trynia.ai

{nia_mcp_server-1.0.22 → nia_mcp_server-1.0.24}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nia-mcp-server"
-version = "1.0.22"
+version = "1.0.24"
 description = "Nia Knowledge Agent"
 readme = "README.md"
 requires-python = ">=3.8"

{nia_mcp_server-1.0.22 → nia_mcp_server-1.0.24}/src/nia_mcp_server/__init__.py

@@ -2,4 +2,5 @@
 NIA MCP Server - Proxy server for NIA Knowledge Agent
 """
 
-__version__ = "1.0.22"
+
+__version__ = "1.0.24"

{nia_mcp_server-1.0.22 → nia_mcp_server-1.0.24}/src/nia_mcp_server/api_client.py

@@ -28,7 +28,7 @@ class NIAApiClient:
         self.client = httpx.AsyncClient(
             headers={
                 "Authorization": f"Bearer {api_key}",
-                "User-Agent": "nia-mcp-server/1.0.22",
+                "User-Agent": "nia-mcp-server/1.0.24",
                 "Content-Type": "application/json"
             },
             timeout=720.0  # 12 minute timeout for deep research operations
@@ -913,4 +913,175 @@ class NIAApiClient:
         except httpx.HTTPStatusError as e:
             raise self._handle_api_error(e)
         except Exception as e:
-            raise APIError(f"Failed to read package file: {str(e)}")
+            raise APIError(f"Failed to read package file: {str(e)}")
+
+    # ========================================================================
+    # CONTEXT SHARING METHODS
+    # ========================================================================
+
+    async def save_context(
+        self,
+        title: str,
+        summary: str,
+        content: str,
+        agent_source: str,
+        tags: List[str] = None,
+        metadata: Dict[str, Any] = None,
+        nia_references: Optional[Dict[str, Any]] = None,
+        edited_files: Optional[List[Dict[str, Any]]] = None
+    ) -> Dict[str, Any]:
+        """Save a conversation context for cross-agent sharing."""
+        try:
+            payload = {
+                "title": title,
+                "summary": summary,
+                "content": content,
+                "agent_source": agent_source,
+                "tags": tags or [],
+                "metadata": metadata or {}
+            }
+
+            # Add new structured fields if provided
+            if nia_references is not None:
+                payload["nia_references"] = nia_references
+            if edited_files is not None:
+                payload["edited_files"] = edited_files
+
+            response = await self.client.post(
+                f"{self.base_url}/v2/contexts",
+                json=payload
+            )
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            raise self._handle_api_error(e)
+        except Exception as e:
+            raise APIError(f"Failed to save context: {str(e)}")
+
+    async def list_contexts(
+        self,
+        limit: int = 20,
+        offset: int = 0,
+        tags: Optional[str] = None,
+        agent_source: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """List user's conversation contexts with pagination and filtering."""
+        try:
+            params = {
+                "limit": limit,
+                "offset": offset
+            }
+
+            if tags:
+                params["tags"] = tags
+            if agent_source:
+                params["agent_source"] = agent_source
+
+            response = await self.client.get(
+                f"{self.base_url}/v2/contexts",
+                params=params
+            )
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            raise self._handle_api_error(e)
+        except Exception as e:
+            raise APIError(f"Failed to list contexts: {str(e)}")
+
+    async def get_context(self, context_id: str) -> Dict[str, Any]:
+        """Get a specific conversation context by ID."""
+        try:
+            response = await self.client.get(f"{self.base_url}/v2/contexts/{context_id}")
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return None
+            raise self._handle_api_error(e)
+        except Exception as e:
+            raise APIError(f"Failed to get context: {str(e)}")
+
+    async def update_context(
+        self,
+        context_id: str,
+        title: Optional[str] = None,
+        summary: Optional[str] = None,
+        content: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Update an existing conversation context."""
+        try:
+            payload = {}
+
+            if title is not None:
+                payload["title"] = title
+            if summary is not None:
+                payload["summary"] = summary
+            if content is not None:
+                payload["content"] = content
+            if tags is not None:
+                payload["tags"] = tags
+            if metadata is not None:
+                payload["metadata"] = metadata
+
+            response = await self.client.put(
+                f"{self.base_url}/v2/contexts/{context_id}",
+                json=payload
+            )
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            raise self._handle_api_error(e)
+        except Exception as e:
+            raise APIError(f"Failed to update context: {str(e)}")
+
+    async def delete_context(self, context_id: str) -> bool:
+        """Delete a conversation context."""
+        try:
+            response = await self.client.delete(f"{self.base_url}/v2/contexts/{context_id}")
+            response.raise_for_status()
+            return True
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return False
+            raise self._handle_api_error(e)
+        except Exception as e:
+            logger.error(f"Failed to delete context: {e}")
+            return False
+
+    async def search_contexts(
+        self,
+        query: str,
+        limit: int = 20,
+        tags: Optional[str] = None,
+        agent_source: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Search conversation contexts by content, title, or summary."""
+        try:
+            params = {
+                "q": query,
+                "limit": limit
+            }
+
+            if tags:
+                params["tags"] = tags
+            if agent_source:
+                params["agent_source"] = agent_source
+
+            response = await self.client.get(
+                f"{self.base_url}/v2/contexts/search",
+                params=params
+            )
+            response.raise_for_status()
+            return response.json()
+
+        except httpx.HTTPStatusError as e:
+            raise self._handle_api_error(e)
+        except Exception as e:
+            raise APIError(f"Failed to search contexts: {str(e)}")

{nia_mcp_server-1.0.22 → nia_mcp_server-1.0.24}/src/nia_mcp_server/server.py

@@ -335,18 +335,19 @@ async def search_documentation(
 
     Args:
         query: Natural language search query. Don't just use keywords or unstrctured query, make a comprehensive question to get the best results possible.
-        sources: List of documentation identifiers to search. Can be:
+        sources: List of documentation identifiers to search. Preferred format is UUID, but also supports:
+            - Source UUIDs (e.g., "550e8400-e29b-41d4-a716-446655440000") - RECOMMENDED
             - Display names (e.g., "Vercel AI SDK - Core")
             - URLs (e.g., "https://sdk.vercel.ai/docs")
-            - Source IDs (UUID format for backwards compatibility)
         include_sources: Whether to include source references in results
 
     Returns:
         Search results with relevant documentation excerpts
 
     Important:
-        - You can now use friendly names instead of UUIDs! Try display names or URLs.
-        - If you don't know the identifiers, use `list_documentation` tool to see available options.
+        - UUIDs are the preferred identifier format for best performance
+        - Use `list_documentation` tool to see available sources and their UUIDs
+        - Display names and URLs are also supported for convenience
     """
     try:
         client = await ensure_api_client()
@@ -356,20 +357,17 @@ async def search_documentation(
             return [TextContent(
                 type="text",
                 text="📚 **Please specify which documentation sources to search:**\n\n"
-                     "1. Use `list_documentation` to see available sources\n"
-                     "2. Then call `search_documentation(\"your query\", [\"source1\", \"source2\"])`\n\n"
-                     "**You can use any of these identifier formats:**\n"
+                     "1. Use `list_documentation` to see available sources and their UUIDs\n"
+                     "2. Then call `search_documentation(\"your query\", [\"uuid1\", \"uuid2\"])`\n\n"
+                     "**Supported identifier formats (UUIDs preferred):**\n"
+                     "- UUIDs: `\"550e8400-e29b-41d4-a716-446655440000\"` - RECOMMENDED\n"
                      "- Display names: `\"Vercel AI SDK - Core\"`\n"
-                     "- URLs: `\"https://docs.trynia.ai/\"`\n"
-                     "- UUIDs: `\"550e8400-e29b-41d4-a716-446655440000\"`\n\n"
-                     "**Example:**\n"
+                     "- URLs: `\"https://docs.trynia.ai/\"`\n\n"
+                     "**Example (preferred):**\n"
                      "```\n"
-                     "search_documentation(\"API reference\", [\"Vercel AI SDK - Core\"])\n"
+                     "search_documentation(\"API reference\", [\"550e8400-e29b-41d4-a716-446655440000\"])\n"
                      "```\n\n"
-                     "**📌 Tip:** Mix different identifier types in the same search:\n"
-                     "```\n"
-                     "search_documentation(\"query\", [\"Display Name\", \"https://docs.example.com/\"])\n"
-                     "```"
+                     "**📌 Tip:** UUIDs provide best performance and reliability"
             )]
         
         # Build messages for the query
@@ -847,7 +845,7 @@ async def rename_resource(
         resource_type: Type of resource - "repository" or "documentation"
         identifier:
             - For repository: Repository in owner/repo format (e.g., "facebook/react")
-            - For documentation: Can be display name, URL, or UUID (e.g., "Vercel AI SDK - Core", "https://docs.trynia.ai/", or "doc-id-123")
+            - For documentation: UUID preferred, also supports display name or URL (e.g., "550e8400-e29b-41d4-a716-446655440000", "Vercel AI SDK - Core", or "https://docs.trynia.ai/")
         new_name: New display name for the resource (1-100 characters)
 
     Returns:
@@ -855,7 +853,7 @@ async def rename_resource(
 
     Examples:
         - rename_resource("repository", "facebook/react", "React Framework")
-        - rename_resource("documentation", "Vercel AI SDK - Core", "Python Official Docs")
+        - rename_resource("documentation", "550e8400-e29b-41d4-a716-446655440000", "Python Official Docs")
         - rename_resource("documentation", "https://docs.trynia.ai/", "NIA Documentation")
     """
     try:
@@ -918,14 +916,14 @@ async def delete_resource(
         resource_type: Type of resource - "repository" or "documentation"
         identifier:
             - For repository: Repository in owner/repo format (e.g., "facebook/react")
-            - For documentation: Can be display name, URL, or UUID (e.g., "Vercel AI SDK - Core", "https://docs.trynia.ai/", or "doc-id-123")
+            - For documentation: UUID preferred, also supports display name or URL (e.g., "550e8400-e29b-41d4-a716-446655440000", "Vercel AI SDK - Core", or "https://docs.trynia.ai/")
 
     Returns:
         Confirmation of deletion
 
     Examples:
         - delete_resource("repository", "facebook/react")
-        - delete_resource("documentation", "Vercel AI SDK - Core")
+        - delete_resource("documentation", "550e8400-e29b-41d4-a716-446655440000")
         - delete_resource("documentation", "https://docs.trynia.ai/")
     """
     try:
@@ -2828,160 +2826,6 @@ async def nia_package_search_read_file(
                  f"- The line range is valid (1-based, max 200 lines)"
         )]
 
-@mcp.tool()
-async def visualize_codebase(
-    repository: str
-) -> List[TextContent]:
-    """
-    Open the graph visualization for an indexed repository in a browser.
-    
-    This tool launches a browser with the interactive graph visualization
-    that shows the code structure, relationships, and dependencies of
-    the indexed codebase.
-    
-    Args:
-        repository: Repository in owner/repo format (e.g., "facebook/react")
-        
-    Returns:
-        Status message with the URL that was opened
-        
-    Examples:
-        - visualize_codebase("facebook/react")
-        - visualize_codebase("langchain-ai/langchain")
-    """
-    try:
-        client = await ensure_api_client()
-        
-        logger.info(f"Looking up repository: {repository}")
-        
-        # List all repositories to find the matching one
-        repositories = await client.list_repositories()
-        
-        # Find the repository by name
-        matching_repo = None
-        for repo in repositories:
-            if repo.get("repository") == repository:
-                matching_repo = repo
-                break
-        
-        if not matching_repo:
-            # Try case-insensitive match as fallback
-            repository_lower = repository.lower()
-            for repo in repositories:
-                if repo.get("repository", "").lower() == repository_lower:
-                    matching_repo = repo
-                    break
-        
-        if not matching_repo:
-            return [TextContent(
-                type="text",
-                text=f"❌ Repository '{repository}' not found.\n\n"
-                     f"Available repositories:\n" +
-                     "\n".join(f"- {r.get('repository')}" for r in repositories if r.get('repository')) +
-                     "\n\nUse `list_repositories` to see all indexed repositories."
-            )]
-        
-        # Check if the repository is fully indexed
-        status = matching_repo.get("status", "unknown")
-        # Use the actual project ID if available, fall back to repository_id
-        repository_id = matching_repo.get("id") or matching_repo.get("repository_id")
-        
-        if not repository_id:
-            return [TextContent(
-                type="text",
-                text=f"❌ No repository ID found for '{repository}'. This may be a data inconsistency."
-            )]
-        
-        if status != "completed":
-            warning_msg = f"⚠️ Note: Repository '{repository}' is currently {status}.\n"
-            if status == "indexing":
-                warning_msg += "The visualization may show incomplete data.\n\n"
-            elif status == "error":
-                error_msg = matching_repo.get("error", "Unknown error")
-                warning_msg += f"Error: {error_msg}\n\n"
-            else:
-                warning_msg += "The visualization may not be available.\n\n"
-        else:
-            warning_msg = ""
-        
-        # Determine the base URL based on the API URL
-        api_base_url = client.base_url
-        if "localhost" in api_base_url or "127.0.0.1" in api_base_url:
-            # Local development
-            app_base_url = "http://localhost:3000"
-        else:
-            # Production
-            app_base_url = "https://app.trynia.ai"
-        
-        # Construct the visualization URL
-        visualization_url = f"{app_base_url}/visualize/{repository_id}"
-        
-        # Try to open the browser
-        try:
-            webbrowser.open(visualization_url)
-            browser_opened = True
-            open_msg = "✅ Opening graph visualization in your default browser..."
-        except Exception as e:
-            logger.warning(f"Failed to open browser: {e}")
-            browser_opened = False
-            open_msg = "⚠️ Could not automatically open browser."
-        
-        # Format the response
-        response_lines = [
-            f"# Graph Visualization: {repository}",
-            "",
-            warning_msg if warning_msg else "",
-            open_msg,
-            "",
-            f"**URL:** {visualization_url}",
-            "",
-        ]
-        
-        if matching_repo.get("display_name"):
-            response_lines.append(f"**Display Name:** {matching_repo['display_name']}")
-        
-        response_lines.extend([
-            f"**Branch:** {matching_repo.get('branch', 'main')}",
-            f"**Status:** {status}",
-            "",
-            "## Features Available:",
-            "- 🔍 Interactive force-directed graph",
-            "- 🎨 Color-coded node types (functions, classes, files, etc.)",
-            "- 🔗 Relationship visualization (calls, imports, inherits, etc.)",
-            "- 💬 Click on any node to chat with that specific code element",
-            "- 🔎 Search and filter capabilities",
-            "- 📊 Graph statistics and insights"
-        ])
-        
-        if not browser_opened:
-            response_lines.extend([
-                "",
-                "**Manual Access:**",
-                f"Copy and paste this URL into your browser: {visualization_url}"
-            ])
-        
-        return [TextContent(
-            type="text",
-            text="\n".join(response_lines)
-        )]
-        
-    except APIError as e:
-        logger.error(f"API Error in visualize_codebase: {e}")
-        if e.status_code == 403 or "free tier limit" in str(e).lower():
-            return [TextContent(
-                type="text",
-                text=f"❌ {str(e)}\n\n💡 Tip: Upgrade to Pro at https://trynia.ai/billing for unlimited access."
-            )]
-        else:
-            return [TextContent(type="text", text=f"❌ {str(e)}")]
-    except Exception as e:
-        logger.error(f"Error in visualize_codebase: {e}")
-        return [TextContent(
-            type="text",
-            text=f"❌ Error opening visualization: {str(e)}"
-        )]
-
-
 @mcp.tool()
 async def nia_bug_report(
     description: str,
@@ -3087,6 +2931,663 @@ async def nia_bug_report(
             )
         ]
 
+# Context Sharing Tools
+
+@mcp.tool()
+async def save_context(
+    title: str,
+    summary: str,
+    content: str,
+    agent_source: str,
+    tags: Optional[List[str]] = None,
+    metadata: Optional[dict] = None,
+    nia_references: Optional[dict] = None,
+    edited_files: Optional[List[dict]] = None
+) -> List[TextContent]:
+    """
+    Save a conversation context for cross-agent sharing.
+
+    This tool enables agents to save conversation contexts that can be shared
+    with other AI agents, creating seamless handoffs between different coding
+    environments (e.g., Cursor → Claude Code).
+
+    Args:
+        title: A descriptive title for the context (1-200 characters)
+        summary: Brief summary of the conversation (10-1000 characters)
+        content: Full conversation context - the agent should compact the conversation history but keep all important parts togethers, as well as code snippets. No excuses.
+        agent_source: Which agent is creating this context (e.g., "cursor", "claude-code", "windsurf")
+        tags: Optional list of searchable tags
+        metadata: Optional metadata like file paths, repositories discussed, etc.
+        nia_references: Structured data about NIA resources used during conversation
+            Format: {
+                "indexed_resources": [{"identifier": "owner/repo", "resource_type": "repository", "purpose": "Used for authentication patterns"}],
+                "search_queries": [{"query": "JWT implementation", "query_type": "codebase", "resources_searched": ["owner/repo"], "key_findings": "Found JWT utils in auth folder"}],
+                "session_summary": "Used NIA to explore authentication patterns and API design"
+            }
+        edited_files: List of files that were modified during conversation
+            Format: [{"file_path": "src/auth.ts", "operation": "modified", "changes_description": "Added JWT validation", "key_changes": ["Added validate() function"]}]
+
+    Returns:
+        Confirmation of successful context save with context ID
+
+    Example:
+        save_context(
+            title="Streaming AI SDK Implementation",
+            summary="Planning conversation about implementing streaming responses with AI SDK",
+            content="User asked about implementing streaming... [agent should include conversation]",
+            agent_source="cursor",
+            tags=["streaming", "ai-sdk", "implementation"],
+            nia_references={
+                "indexed_resources": [{"identifier": "vercel/ai", "resource_type": "repository", "purpose": "Reference for streaming implementation"}],
+                "search_queries": [{"query": "streaming API", "query_type": "documentation", "key_findings": "Found useChat hook with streaming"}]
+            },
+            edited_files=[{"file_path": "src/chat.ts", "operation": "created", "changes_description": "Added streaming chat component"}]
+        )
+    """
+    try:
+        # Validate input parameters
+        if not title or not title.strip():
+            return [TextContent(type="text", text="❌ Error: Title is required")]
+
+        if len(title) > 200:
+            return [TextContent(type="text", text="❌ Error: Title must be 200 characters or less")]
+
+        if not summary or len(summary) < 10:
+            return [TextContent(type="text", text="❌ Error: Summary must be at least 10 characters")]
+
+        if len(summary) > 1000:
+            return [TextContent(type="text", text="❌ Error: Summary must be 1000 characters or less")]
+
+        if not content or len(content) < 50:
+            return [TextContent(type="text", text="❌ Error: Content must be at least 50 characters")]
+
+        if not agent_source or not agent_source.strip():
+            return [TextContent(type="text", text="❌ Error: Agent source is required")]
+
+        client = await ensure_api_client()
+
+        logger.info(f"Saving context: title='{title}', agent={agent_source}, content_length={len(content)}")
+
+        result = await client.save_context(
+            title=title.strip(),
+            summary=summary.strip(),
+            content=content,
+            agent_source=agent_source.strip(),
+            tags=tags or [],
+            metadata=metadata or {},
+            nia_references=nia_references,
+            edited_files=edited_files or []
+        )
+
+        context_id = result.get("id")
+
+        return [TextContent(
+            type="text",
+            text=f"✅ **Context Saved Successfully!**\n\n"
+                 f"🆔 **Context ID:** `{context_id}`\n"
+                 f"📝 **Title:** {title}\n"
+                 f"🤖 **Source Agent:** {agent_source}\n"
+                 f"📊 **Content Length:** {len(content):,} characters\n"
+                 f"🏷️ **Tags:** {', '.join(tags) if tags else 'None'}\n\n"
+                 f"**Next Steps:**\n"
+                 f"• Other agents can now retrieve this context using the context ID\n"
+                 f"• Use `search_contexts` to find contexts by content or tags\n"
+                 f"• Use `list_contexts` to see all your saved contexts\n\n"
+                 f"🔗 **Share this context:** Provide the context ID `{context_id}` to other agents"
+        )]
+
+    except APIError as e:
+        logger.error(f"API Error saving context: {e}")
+        return [TextContent(type="text", text=f"❌ API Error: {str(e)}")]
+    except Exception as e:
+        logger.error(f"Error saving context: {e}")
+        return [TextContent(type="text", text=f"❌ Error saving context: {str(e)}")]
+
+@mcp.tool()
+async def list_contexts(
+    limit: int = 20,
+    offset: int = 0,
+    tags: Optional[str] = None,
+    agent_source: Optional[str] = None
+) -> List[TextContent]:
+    """
+    List saved conversation contexts with pagination and filtering.
+
+    Args:
+        limit: Number of contexts to return (1-100, default: 20)
+        offset: Number of contexts to skip for pagination (default: 0)
+        tags: Comma-separated tags to filter by (optional)
+        agent_source: Filter by specific agent source (optional)
+
+    Returns:
+        List of conversation contexts with pagination info
+
+    Examples:
+        - list_contexts() - List recent 20 contexts
+        - list_contexts(limit=50) - List recent 50 contexts
+        - list_contexts(tags="streaming,ai-sdk") - Filter by tags
+        - list_contexts(agent_source="cursor") - Only contexts from Cursor
+    """
+    try:
+        # Validate parameters
+        if limit < 1 or limit > 100:
+            return [TextContent(type="text", text="❌ Error: Limit must be between 1 and 100")]
+
+        if offset < 0:
+            return [TextContent(type="text", text="❌ Error: Offset must be 0 or greater")]
+
+        client = await ensure_api_client()
+
+        result = await client.list_contexts(
+            limit=limit,
+            offset=offset,
+            tags=tags,
+            agent_source=agent_source
+        )
+
+        contexts = result.get("contexts", [])
+        pagination = result.get("pagination", {})
+
+        if not contexts:
+            response = "📭 **No Contexts Found**\n\n"
+            if tags or agent_source:
+                response += "No contexts match your filters.\n\n"
+            else:
+                response += "You haven't saved any contexts yet.\n\n"
+
+            response += "**Get started:**\n"
+            response += "• Use `save_context` to save a conversation for cross-agent sharing\n"
+            response += "• Perfect for handoffs between Cursor and Claude Code!"
+
+            return [TextContent(type="text", text=response)]
+
+        # Format the response
+        response = f"📚 **Your Conversation Contexts** ({pagination.get('total', len(contexts))} total)\n\n"
+
+        for i, context in enumerate(contexts, offset + 1):
+            created_at = context.get('created_at', '')
+            if created_at:
+                # Format datetime for better readability
+                try:
+                    from datetime import datetime
+                    dt = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+                    formatted_date = dt.strftime('%Y-%m-%d %H:%M UTC')
+                except:
+                    formatted_date = created_at
+            else:
+                formatted_date = 'Unknown'
+
+            response += f"**{i}. {context['title']}**\n"
+            response += f"   🆔 ID: `{context['id']}`\n"
+            response += f"   🤖 Source: {context['agent_source']}\n"
+            response += f"   📅 Created: {formatted_date}\n"
+            response += f"   📝 Summary: {context['summary'][:100]}{'...' if len(context['summary']) > 100 else ''}\n"
+            if context.get('tags'):
+                response += f"   🏷️ Tags: {', '.join(context['tags'])}\n"
+            response += "\n"
+
+        # Add pagination info
+        if pagination.get('has_more'):
+            next_offset = offset + limit
+            response += f"📄 **Pagination:** Showing {offset + 1}-{offset + len(contexts)} of {pagination.get('total')}\n"
+            response += f"   Use `list_contexts(offset={next_offset})` for next page\n"
+
+        response += "\n**Actions:**\n"
+        response += "• `retrieve_context(context_id)` - Get full context\n"
+        response += "• `search_contexts(query)` - Search contexts\n"
+        response += "• `delete_context(context_id)` - Remove context"
+
+        return [TextContent(type="text", text=response)]
+
+    except APIError as e:
+        logger.error(f"API Error listing contexts: {e}")
+        return [TextContent(type="text", text=f"❌ API Error: {str(e)}")]
+    except Exception as e:
+        logger.error(f"Error listing contexts: {e}")
+        return [TextContent(type="text", text=f"❌ Error listing contexts: {str(e)}")]
+
+@mcp.tool()
+async def retrieve_context(context_id: str) -> List[TextContent]:
+    """
+    Retrieve a specific conversation context by ID.
+
+    Use this tool to get the full conversation context that was saved by
+    another agent. Perfect for getting strategic context from Cursor
+    when working in Claude Code.
+
+    Args:
+        context_id: The unique ID of the context to retrieve
+
+    Returns:
+        Full conversation context with metadata
+
+    Example:
+        retrieve_context("550e8400-e29b-41d4-a716-446655440000")
+    """
+    try:
+        if not context_id or not context_id.strip():
+            return [TextContent(type="text", text="❌ Error: Context ID is required")]
+
+        client = await ensure_api_client()
+
+        context = await client.get_context(context_id.strip())
+
+        if not context:
+            return [TextContent(
+                type="text",
+                text=f"❌ **Context Not Found**\n\n"
+                     f"Context ID `{context_id}` was not found.\n\n"
+                     f"**Possible reasons:**\n"
+                     f"• The context ID is incorrect\n"
+                     f"• The context belongs to a different user\n"
+                     f"• The context has been deleted\n\n"
+                     f"Use `list_contexts()` to see your available contexts."
+            )]
+
+        # Format the context display
+        created_at = context.get('created_at', '')
+        if created_at:
+            try:
+                from datetime import datetime
+                dt = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+                formatted_date = dt.strftime('%Y-%m-%d %H:%M UTC')
+            except:
+                formatted_date = created_at
+        else:
+            formatted_date = 'Unknown'
+
+        updated_at = context.get('updated_at', '')
+        if updated_at:
+            try:
+                from datetime import datetime
+                dt = datetime.fromisoformat(updated_at.replace('Z', '+00:00'))
+                formatted_updated = dt.strftime('%Y-%m-%d %H:%M UTC')
+            except:
+                formatted_updated = updated_at
+        else:
+            formatted_updated = None
+
+        response = f"📋 **Context: {context['title']}**\n\n"
+        response += f"🆔 **ID:** `{context['id']}`\n"
+        response += f"🤖 **Source Agent:** {context['agent_source']}\n"
+        response += f"📅 **Created:** {formatted_date}\n"
+        if formatted_updated:
+            response += f"🔄 **Updated:** {formatted_updated}\n"
+
+        if context.get('tags'):
+            response += f"🏷️ **Tags:** {', '.join(context['tags'])}\n"
+
+        response += f"\n📝 **Summary:**\n{context['summary']}\n\n"
+
+        # Add NIA References - CRITICAL for context handoffs
+        nia_references = context.get('nia_references', {})
+        if nia_references:
+            response += "🧠 **NIA RESOURCES USED - RECOMMENDED ACTIONS:**\n"
+
+            indexed_resources = nia_references.get('indexed_resources', [])
+            if indexed_resources:
+                response += "**📦 Re-index these resources:**\n"
+                for resource in indexed_resources:
+                    identifier = resource.get('identifier', 'Unknown')
+                    resource_type = resource.get('resource_type', 'unknown')
+                    purpose = resource.get('purpose', 'No purpose specified')
+
+                    if resource_type == 'repository':
+                        response += f"• `Index {identifier}` - {purpose}\n"
+                    elif resource_type == 'documentation':
+                        response += f"• `Index documentation {identifier}` - {purpose}\n"
+                    else:
+                        response += f"• `Index {identifier}` ({resource_type}) - {purpose}\n"
+                response += "\n"
+
+            search_queries = nia_references.get('search_queries', [])
+            if search_queries:
+                response += "**🔍 Useful search queries to re-run:**\n"
+                for query in search_queries:
+                    query_text = query.get('query', 'Unknown query')
+                    query_type = query.get('query_type', 'search')
+                    key_findings = query.get('key_findings', 'No findings specified')
+                    resources_searched = query.get('resources_searched', [])
+
+                    response += f"• **Query:** `{query_text}` ({query_type})\n"
+                    if resources_searched:
+                        response += f"  **Resources:** {', '.join(resources_searched)}\n"
+                    response += f"  **Key Findings:** {key_findings}\n"
+                response += "\n"
+
+            session_summary = nia_references.get('session_summary')
+            if session_summary:
+                response += f"**📋 NIA Session Summary:** {session_summary}\n\n"
+
+        # Add Edited Files - CRITICAL for code handoffs
+        edited_files = context.get('edited_files', [])
+        if edited_files:
+            response += "📝 **FILES MODIFIED - READ THESE TO GET UP TO SPEED:**\n"
+            for file_info in edited_files:
+                file_path = file_info.get('file_path', 'Unknown file')
+                operation = file_info.get('operation', 'modified')
+                changes_desc = file_info.get('changes_description', 'No description')
+                key_changes = file_info.get('key_changes', [])
+                language = file_info.get('language', '')
+
+                operation_emoji = {
+                    'created': '🆕',
+                    'modified': '✏️',
+                    'deleted': '🗑️'
+                }.get(operation, '📄')
+
+                response += f"• {operation_emoji} **`{file_path}`** ({operation})\n"
+                response += f"  **Changes:** {changes_desc}\n"
+
+                if key_changes:
+                    response += f"  **Key Changes:** {', '.join(key_changes)}\n"
+                if language:
+                    response += f"  **Language:** {language}\n"
+
+                response += f"  **💡 Action:** Read this file with: `Read {file_path}`\n"
+            response += "\n"
+
+        # Add metadata if available
+        metadata = context.get('metadata', {})
+        if metadata:
+            response += f"📊 **Additional Metadata:**\n"
+            for key, value in metadata.items():
+                if isinstance(value, list):
+                    response += f"• **{key}:** {', '.join(map(str, value))}\n"
+                else:
+                    response += f"• **{key}:** {value}\n"
+            response += "\n"
+
+        response += f"📄 **Full Context:**\n\n{context['content']}\n\n"
+
+        response += f"---\n"
+        response += f"🚀 **NEXT STEPS FOR SEAMLESS HANDOFF:**\n"
+        response += f"• This context was created by **{context['agent_source']}**\n"
+
+        if nia_references.get('search_queries'):
+            response += f"• **RECOMMENDED:** Re-run the search queries to get the same insights\n"
+        if edited_files:
+            response += f"• **ESSENTIAL:** Read the modified files above to understand code changes\n"
+
+        response += f"• Use the summary and full context to understand the strategic planning\n"
+
+        return [TextContent(type="text", text=response)]
+
+    except APIError as e:
+        logger.error(f"API Error retrieving context: {e}")
+        return [TextContent(type="text", text=f"❌ API Error: {str(e)}")]
+    except Exception as e:
+        logger.error(f"Error retrieving context: {e}")
+        return [TextContent(type="text", text=f"❌ Error retrieving context: {str(e)}")]
+
+@mcp.tool()
+async def search_contexts(
+    query: str,
+    limit: int = 20,
+    tags: Optional[str] = None,
+    agent_source: Optional[str] = None
+) -> List[TextContent]:
+    """
+    Search conversation contexts by content, title, or summary.
+
+    Perfect for finding relevant contexts when you remember part of the
+    conversation but not the exact context ID.
+
+    Args:
+        query: Search query to match against title, summary, content, and tags
+        limit: Maximum number of results to return (1-100, default: 20)
+        tags: Comma-separated tags to filter by (optional)
+        agent_source: Filter by specific agent source (optional)
+
+    Returns:
+        Search results with matching contexts
+
+    Examples:
+        - search_contexts("streaming AI SDK")
+        - search_contexts("authentication", tags="security,implementation")
+        - search_contexts("database", agent_source="cursor")
+    """
+    try:
+        # Validate parameters
+        if not query or not query.strip():
+            return [TextContent(type="text", text="❌ Error: Search query is required")]
+
+        if limit < 1 or limit > 100:
+            return [TextContent(type="text", text="❌ Error: Limit must be between 1 and 100")]
+
+        client = await ensure_api_client()
+
+        result = await client.search_contexts(
+            query=query.strip(),
+            limit=limit,
+            tags=tags,
+            agent_source=agent_source
+        )
+
+        contexts = result.get("contexts", [])
+
+        if not contexts:
+            response = f"🔍 **No Results Found**\n\n"
+            response += f"No contexts match your search query: \"{query}\"\n\n"
+
+            if tags or agent_source:
+                response += f"**Active filters:**\n"
+                if tags:
+                    response += f"• Tags: {tags}\n"
+                if agent_source:
+                    response += f"• Agent: {agent_source}\n"
+                response += "\n"
+
+            response += f"**Suggestions:**\n"
+            response += f"• Try different keywords\n"
+            response += f"• Remove filters to broaden search\n"
+            response += f"• Use `list_contexts()` to see all contexts"
+
+            return [TextContent(type="text", text=response)]
+
+        # Format search results
+        response = f"🔍 **Search Results for \"{query}\"** ({len(contexts)} found)\n\n"
+
+        for i, context in enumerate(contexts, 1):
+            created_at = context.get('created_at', '')
+            if created_at:
+                try:
+                    from datetime import datetime
+                    dt = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+                    formatted_date = dt.strftime('%Y-%m-%d %H:%M UTC')
+                except:
+                    formatted_date = created_at
+            else:
+                formatted_date = 'Unknown'
+
+            response += f"**{i}. {context['title']}**\n"
+            response += f"   🆔 ID: `{context['id']}`\n"
+            response += f"   🤖 Source: {context['agent_source']}\n"
+            response += f"   📅 Created: {formatted_date}\n"
+            response += f"   📝 Summary: {context['summary'][:150]}{'...' if len(context['summary']) > 150 else ''}\n"
+
+            if context.get('tags'):
+                response += f"   🏷️ Tags: {', '.join(context['tags'])}\n"
+
+            response += "\n"
+
+        response += f"**Actions:**\n"
+        response += f"• `retrieve_context(context_id)` - Get full context\n"
+        response += f"• Refine search with different keywords\n"
+        response += f"• Use tags or agent filters for better results"
+
+        return [TextContent(type="text", text=response)]
+
+    except APIError as e:
+        logger.error(f"API Error searching contexts: {e}")
+        return [TextContent(type="text", text=f"❌ API Error: {str(e)}")]
+    except Exception as e:
+        logger.error(f"Error searching contexts: {e}")
+        return [TextContent(type="text", text=f"❌ Error searching contexts: {str(e)}")]
+
+@mcp.tool()
+async def update_context(
+    context_id: str,
+    title: Optional[str] = None,
+    summary: Optional[str] = None,
+    content: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+    metadata: Optional[dict] = None
+) -> List[TextContent]:
+    """
+    Update an existing conversation context.
+
+    Args:
+        context_id: The unique ID of the context to update
+        title: Updated title (optional)
+        summary: Updated summary (optional)
+        content: Updated content (optional)
+        tags: Updated tags list (optional)
+        metadata: Updated metadata (optional)
+
+    Returns:
+        Confirmation of successful update
+
+    Example:
+        update_context(
+            context_id="550e8400-e29b-41d4-a716-446655440000",
+            title="Updated: Streaming AI SDK Implementation",
+            tags=["streaming", "ai-sdk", "completed"]
+        )
+    """
+    try:
+        if not context_id or not context_id.strip():
+            return [TextContent(type="text", text="❌ Error: Context ID is required")]
+
+        # Check that at least one field is being updated
+        if not any([title, summary, content, tags is not None, metadata is not None]):
+            return [TextContent(
+                type="text",
+                text="❌ Error: At least one field must be provided for update"
+            )]
+
+        # Validate fields if provided
+        if title is not None and (not title.strip() or len(title) > 200):
+            return [TextContent(
+                type="text",
+                text="❌ Error: Title must be 1-200 characters"
+            )]
+
+        if summary is not None and (len(summary) < 10 or len(summary) > 1000):
+            return [TextContent(
+                type="text",
+                text="❌ Error: Summary must be 10-1000 characters"
+            )]
+
+        if content is not None and len(content) < 50:
+            return [TextContent(
+                type="text",
+                text="❌ Error: Content must be at least 50 characters"
+            )]
+
+        if tags is not None and len(tags) > 10:
+            return [TextContent(
+                type="text",
+                text="❌ Error: Maximum 10 tags allowed"
+            )]
+
+        client = await ensure_api_client()
+
+        result = await client.update_context(
+            context_id=context_id.strip(),
+            title=title.strip() if title else None,
+            summary=summary.strip() if summary else None,
+            content=content,
+            tags=tags,
+            metadata=metadata
+        )
+
+        if not result:
+            return [TextContent(
+                type="text",
+                text=f"❌ Error: Context with ID `{context_id}` not found"
+            )]
+
+        # List updated fields
+        updated_fields = []
+        if title is not None:
+            updated_fields.append("title")
+        if summary is not None:
+            updated_fields.append("summary")
+        if content is not None:
+            updated_fields.append("content")
+        if tags is not None:
+            updated_fields.append("tags")
+        if metadata is not None:
+            updated_fields.append("metadata")
+
+        response = f"✅ **Context Updated Successfully!**\n\n"
+        response += f"🆔 **Context ID:** `{context_id}`\n"
+        response += f"📝 **Title:** {result['title']}\n"
+        response += f"🔄 **Updated Fields:** {', '.join(updated_fields)}\n"
+        response += f"🤖 **Source Agent:** {result['agent_source']}\n\n"
+
+        response += f"**Current Status:**\n"
+        response += f"• **Tags:** {', '.join(result['tags']) if result.get('tags') else 'None'}\n"
+        response += f"• **Content Length:** {len(result['content']):,} characters\n\n"
+
+        response += f"Use `retrieve_context('{context_id}')` to see the full updated context."
+
+        return [TextContent(type="text", text=response)]
+
+    except APIError as e:
+        logger.error(f"API Error updating context: {e}")
+        return [TextContent(type="text", text=f"❌ API Error: {str(e)}")]
+    except Exception as e:
+        logger.error(f"Error updating context: {e}")
+        return [TextContent(type="text", text=f"❌ Error updating context: {str(e)}")]
+
+@mcp.tool()
+async def delete_context(context_id: str) -> List[TextContent]:
+    """
+    Delete a conversation context.
+
+    Args:
+        context_id: The unique ID of the context to delete
+
+    Returns:
+        Confirmation of successful deletion
+
+    Example:
+        delete_context("550e8400-e29b-41d4-a716-446655440000")
+    """
+    try:
+        if not context_id or not context_id.strip():
+            return [TextContent(type="text", text="❌ Error: Context ID is required")]
+
+        client = await ensure_api_client()
+
+        success = await client.delete_context(context_id.strip())
+
+        if success:
+            return [TextContent(
+                type="text",
+                text=f"✅ **Context Deleted Successfully!**\n\n"
+                     f"🆔 **Context ID:** `{context_id}`\n\n"
+                     f"The context has been permanently removed from your account.\n"
+                     f"This action cannot be undone.\n\n"
+                     f"Use `list_contexts()` to see your remaining contexts."
+            )]
+        else:
+            return [TextContent(
+                type="text",
+                text=f"❌ **Context Not Found**\n\n"
+                     f"Context ID `{context_id}` was not found or has already been deleted.\n\n"
+                     f"Use `list_contexts()` to see your available contexts."
+            )]
+
+    except APIError as e:
+        logger.error(f"API Error deleting context: {e}")
+        return [TextContent(type="text", text=f"❌ API Error: {str(e)}")]
+    except Exception as e:
+        logger.error(f"Error deleting context: {e}")
+        return [TextContent(type="text", text=f"❌ Error deleting context: {str(e)}")]
+
 # Resources
 
 # Note: FastMCP doesn't have list_resources or read_resource decorators