kg-mcp 0.1.8__py3-none-any.whl

kg_mcp/mcp/change_schemas.py

@@ -0,0 +1,140 @@
+"""
+Pydantic schemas for structured code change tracking.
+
+These models define the format for kg_track_changes input,
+enabling detailed tracking of file and symbol modifications.
+"""
+
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class SymbolChange(BaseModel):
+    """
+    A modified symbol (function, class, method, variable).
+    
+    This represents a single code symbol that was added, modified, or deleted
+    within a file. The agent should provide this information after making
+    changes to enable precise tracking in the knowledge graph.
+    
+    Example:
+        {
+            "name": "calculate_tax",
+            "kind": "function",
+            "line_start": 10,
+            "line_end": 25,
+            "signature": "def calculate_tax(income: float) -> float",
+            "change_type": "modified"
+        }
+    """
+    
+    name: str = Field(
+        ..., 
+        description="Symbol name. For methods, use 'ClassName.method_name' format. "
+                    "Examples: 'calculate_tax', 'UserService.authenticate', 'CONFIG'"
+    )
+    kind: Literal["function", "method", "class", "variable"] = Field(
+        ...,
+        description="Type of symbol: 'function' for standalone functions, "
+                    "'method' for class methods, 'class' for class definitions, "
+                    "'variable' for module-level constants/variables"
+    )
+    line_start: int = Field(
+        ..., 
+        ge=1,
+        description="First line number of the symbol definition (1-indexed)"
+    )
+    line_end: int = Field(
+        ..., 
+        ge=1,
+        description="Last line number of the symbol definition (1-indexed)"
+    )
+    signature: Optional[str] = Field(
+        None,
+        description="Full signature including parameters and return type. "
+                    "Example: 'def calculate_tax(income: float, rate: float = 0.2) -> float'"
+    )
+    change_type: Literal["added", "modified", "deleted", "renamed"] = Field(
+        ...,
+        description="What happened to this symbol: 'added' for new symbols, "
+                    "'modified' for changed implementations, 'deleted' for removed symbols, "
+                    "'renamed' for renamed symbols (old name)"
+    )
+
+
+class FileChange(BaseModel):
+    """
+    A single file modification with its symbols.
+    
+    This represents a file that was created, modified, or deleted,
+    along with the specific symbols that changed within it.
+    
+    Example:
+        {
+            "path": "/project/src/utils.py",
+            "change_type": "modified",
+            "language": "python",
+            "symbols": [
+                {
+                    "name": "format_currency",
+                    "kind": "function",
+                    "line_start": 45,
+                    "line_end": 52,
+                    "signature": "def format_currency(amount: float) -> str",
+                    "change_type": "added"
+                }
+            ]
+        }
+    """
+    
+    path: str = Field(
+        ...,
+        description="Absolute or project-relative path to the file. "
+                    "Examples: '/Users/dev/project/src/auth.py', 'src/auth.py'"
+    )
+    change_type: Literal["created", "modified", "deleted", "renamed"] = Field(
+        ...,
+        description="What happened to this file: 'created' for new files, "
+                    "'modified' for changed files, 'deleted' for removed files, "
+                    "'renamed' for renamed files"
+    )
+    language: Optional[str] = Field(
+        None,
+        description="Programming language. Auto-detected from extension if not provided. "
+                    "Examples: 'python', 'typescript', 'javascript', 'go', 'rust'"
+    )
+    symbols: List[SymbolChange] = Field(
+        default_factory=list,
+        description="List of symbols that changed in this file. "
+                    "RECOMMENDED: Always provide this for better tracking. "
+                    "Include ALL functions/classes/methods that were added, modified, or deleted."
+    )
+    content_hash: Optional[str] = Field(
+        None,
+        description="SHA256 hash of file content for change detection. "
+                    "Optional but useful for deduplication."
+    )
+
+
+class TrackChangesInput(BaseModel):
+    """
+    Complete input for kg_track_changes tool.
+    
+    This is the structured format the agent should use when calling
+    kg_track_changes after making file modifications.
+    """
+    
+    project_id: str = Field(
+        ...,
+        description="Project identifier. Use the workspace/repository folder name."
+    )
+    changes: List[FileChange] = Field(
+        ...,
+        min_length=1,
+        description="List of file changes. Must include at least one file."
+    )
+    check_impact: bool = Field(
+        default=True,
+        description="Whether to run impact analysis to find affected goals/tests."
+    )

kg_mcp/mcp/prompts.py

@@ -0,0 +1,223 @@
+"""
+MCP Prompt definitions for the Knowledge Graph Memory Server.
+Prompts are reusable templates that instruct agents on workflows.
+"""
+
+import logging
+
+from mcp.server.fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+
+def register_prompts(mcp: FastMCP) -> None:
+    """Register all MCP prompts with the server."""
+
+    @mcp.prompt()
+    def StartCodingWithKG(project_id: str) -> str:
+        """
+        Instructs an IDE agent to use the Knowledge Graph for context-aware coding.
+
+        This prompt template should be invoked at the start of a coding session.
+        It guides the agent through the simplified 2-tool workflow.
+        """
+        return f"""# Knowledge Graph-Powered Coding Assistant
+
+You are a coding assistant enhanced with a persistent Knowledge Graph memory.
+**Project ID:** `{project_id}`
+
+## Your Workflow (Simplified)
+
+### 🚀 Step 1: Start Every Task with kg_autopilot
+
+**ALWAYS** call this at the START of every task:
+
+```
+kg_autopilot(
+    project_id="{project_id}",
+    user_text="<paste the user's request here>",
+    files=["<relevant", "files>"],
+    search_query="<optional: keywords to search>"
+)
+```
+
+This single call:
+- ✅ Ingests and analyzes the request
+- ✅ Extracts goals, constraints, preferences
+- ✅ Returns the full context pack
+- ✅ Optionally searches existing knowledge
+
+**Read the returned markdown context carefully!**
+
+### 🔗 Step 2: Track Changes with kg_track_changes
+
+**ALWAYS** call this AFTER modifying files:
+
+```
+kg_track_changes(
+    project_id="{project_id}",
+    changed_paths=["path/to/modified/file.py"],
+    related_goal_ids=["<goal_id from context>"]
+)
+```
+
+This tracks your changes and returns impact analysis.
+
+## Quick Reference
+
+| When | Tool |
+|------|------|
+| START of every task | `kg_autopilot` |
+| AFTER file changes | `kg_track_changes` |
+
+## Important Rules
+
+1. **Never skip kg_autopilot** at task start - it's your persistent memory
+2. **Never skip kg_track_changes** after modifying code - it maintains traceability
+3. **Read the context pack** - it contains goals, preferences, and pain points to avoid
+
+---
+
+Now, let's begin! What would you like to work on?
+"""
+
+
+    @mcp.prompt()
+    def ReviewGoals(project_id: str) -> str:
+        """
+        Prompt for reviewing and managing project goals.
+        """
+        return f"""# Goal Review Session
+
+**Project:** `{project_id}`
+
+Let's review the current goals for this project.
+
+## To Get Started
+
+1. First, let me fetch the active goals:
+   ```
+   Use resource: kg://projects/{project_id}/active-goals
+   ```
+
+2. Then we can:
+   - Mark goals as complete
+   - Reprioritize goals
+   - Break down large goals into subgoals
+   - Identify blockers (pain points)
+   - Update strategies
+
+## Questions to Consider
+
+- Are all active goals still relevant?
+- Are priorities correctly assigned?
+- Are there any blocked goals that need attention?
+- Should any goals be decomposed into smaller tasks?
+
+Let me retrieve the current goals and we'll discuss.
+"""
+
+    @mcp.prompt()
+    def DebugWithContext(project_id: str, error_message: str = "") -> str:
+        """
+        Prompt for debugging with knowledge graph context.
+        """
+        error_section = f"\n**Error:**\n```\n{error_message}\n```\n" if error_message else ""
+
+        return f"""# Debugging Session
+
+**Project:** `{project_id}`
+{error_section}
+
+## Debugging Workflow
+
+1. **Ingest the error context:**
+   ```
+   kg_ingest_message(
+       project_id="{project_id}",
+       user_text="Debugging error: {error_message[:100] if error_message else 'describe the issue'}",
+       tags=["debug", "error"]
+   )
+   ```
+
+2. **Get relevant context:**
+   ```
+   kg_context_pack(
+       project_id="{project_id}",
+       query="error debugging"
+   )
+   ```
+
+3. **Check for known pain points:**
+   - The context pack will include open pain points
+   - Check if this error relates to known issues
+
+4. **Search for related code:**
+   ```
+   kg_search(
+       project_id="{project_id}",
+       query="relevant keywords from error",
+       filters=["CodeArtifact"]
+   )
+   ```
+
+5. **If you find the fix**, remember to:
+   - Log it as a resolved pain point
+   - Link the fixed code to the goal
+
+Let's start debugging!
+"""
+
+    @mcp.prompt()
+    def DocumentPreferences(project_id: str) -> str:
+        """
+        Prompt for documenting user preferences.
+        """
+        return f"""# Preference Documentation
+
+**Project:** `{project_id}`
+
+I'll help you document your coding preferences. These will be remembered
+and applied to all future coding tasks.
+
+## Categories to Consider
+
+### 1. Coding Style
+- Formatting preferences (tabs vs spaces, line length)
+- Naming conventions (camelCase, snake_case)
+- Comment style
+- Import organization
+
+### 2. Architecture
+- Design patterns preferred (SOLID, DDD, etc.)
+- Architectural style (monolith, microservices)
+- Error handling approach
+- Logging strategy
+
+### 3. Testing
+- Test framework preference
+- Coverage requirements
+- Test naming conventions
+- Mock/stub strategy
+
+### 4. Tools & Technologies
+- Preferred libraries
+- Build tools
+- Linting/formatting tools
+- CI/CD preferences
+
+### 5. Output Format
+- How you like explanations formatted
+- Level of detail in comments
+- Documentation style
+
+## To Record a Preference
+
+When you tell me a preference, I'll save it using `kg_ingest_message`.
+For example, if you say "I prefer functional programming patterns",
+I'll extract and store that preference.
+
+What preferences would you like to document?
+"""
+
+    logger.info("MCP prompts registered successfully")

kg_mcp/mcp/resources.py

@@ -0,0 +1,218 @@
+"""
+MCP Resource definitions for the Knowledge Graph Memory Server.
+Resources provide read-only access to graph data.
+"""
+
+import logging
+from typing import Any, Dict, List
+
+from mcp.server.fastmcp import FastMCP
+
+from kg_mcp.kg.repo import get_repository
+
+logger = logging.getLogger(__name__)
+
+
+def register_resources(mcp: FastMCP) -> None:
+    """Register all MCP resources with the server."""
+
+    @mcp.resource("kg://projects/{project_id}/active-goals")
+    async def get_active_goals(project_id: str) -> str:
+        """
+        Get all active goals for a project.
+
+        Returns a Markdown-formatted list of active goals with their
+        acceptance criteria, constraints, and strategies.
+        """
+        logger.info(f"Resource requested: active-goals for project {project_id}")
+
+        try:
+            repo = get_repository()
+            goals = await repo.get_active_goals(project_id)
+
+            if not goals:
+                return f"# Active Goals for {project_id}\n\nNo active goals found."
+
+            lines = [f"# Active Goals for {project_id}\n"]
+
+            for i, goal in enumerate(goals, 1):
+                priority = goal.get("priority", 3)
+                emoji = {1: "🔴", 2: "🟠", 3: "🟡", 4: "🟢", 5: "⚪"}.get(priority, "⚪")
+
+                lines.append(f"## {i}. {emoji} {goal.get('title', 'Untitled')}")
+                lines.append(f"**ID:** `{goal.get('id', 'N/A')}`")
+                lines.append(f"**Priority:** {priority}")
+
+                if goal.get("description"):
+                    lines.append(f"\n{goal['description']}")
+
+                if goal.get("acceptance_criteria"):
+                    lines.append("\n**Acceptance Criteria:**")
+                    for ac in goal["acceptance_criteria"]:
+                        criterion = ac.get("criterion", ac) if isinstance(ac, dict) else ac
+                        lines.append(f"- [ ] {criterion}")
+
+                if goal.get("constraints"):
+                    lines.append("\n**Constraints:**")
+                    for c in goal["constraints"]:
+                        if isinstance(c, dict) and c:
+                            lines.append(f"- [{c.get('severity', 'must')}] {c.get('description', '')}")
+
+                if goal.get("strategies"):
+                    lines.append("\n**Strategies:**")
+                    for s in goal["strategies"]:
+                        if isinstance(s, dict) and s:
+                            lines.append(f"- {s.get('title', 'Strategy')}: {s.get('approach', '')}")
+
+                lines.append("")
+
+            return "\n".join(lines)
+
+        except Exception as e:
+            logger.error(f"Failed to get active goals: {e}")
+            return f"# Error\n\nFailed to retrieve active goals: {e}"
+
+    @mcp.resource("kg://projects/{project_id}/preferences")
+    async def get_preferences(project_id: str) -> str:
+        """
+        Get user preferences for a project.
+
+        Returns coding style preferences, architectural preferences,
+        tool preferences, and output format preferences.
+        """
+        logger.info(f"Resource requested: preferences for project {project_id}")
+
+        try:
+            repo = get_repository()
+            # Use default_user for now; could be parameterized
+            preferences = await repo.get_preferences("default_user")
+
+            if not preferences:
+                return f"# Preferences for {project_id}\n\nNo preferences configured."
+
+            lines = [f"# Preferences for {project_id}\n"]
+
+            # Group by category
+            by_category: Dict[str, List[Dict[str, Any]]] = {}
+            for pref in preferences:
+                cat = pref.get("category", "other")
+                if cat not in by_category:
+                    by_category[cat] = []
+                by_category[cat].append(pref)
+
+            for category, prefs in by_category.items():
+                lines.append(f"## {category.replace('_', ' ').title()}\n")
+                for p in prefs:
+                    strength = p.get("strength", "prefer")
+                    prefix = {
+                        "require": "✅ REQUIRE",
+                        "avoid": "❌ AVOID",
+                        "prefer": "💡 PREFER",
+                    }.get(strength, "💡")
+                    lines.append(f"- {prefix}: {p.get('preference', '')}")
+                lines.append("")
+
+            return "\n".join(lines)
+
+        except Exception as e:
+            logger.error(f"Failed to get preferences: {e}")
+            return f"# Error\n\nFailed to retrieve preferences: {e}"
+
+    @mcp.resource("kg://projects/{project_id}/goal/{goal_id}/subgraph")
+    async def get_goal_subgraph(project_id: str, goal_id: str) -> str:
+        """
+        Get the subgraph around a specific goal.
+
+        Returns the goal and all entities connected within 2 hops:
+        constraints, strategies, pain points, code artifacts, tests.
+        """
+        logger.info(f"Resource requested: subgraph for goal {goal_id}")
+
+        try:
+            repo = get_repository()
+            subgraph = await repo.get_goal_subgraph(goal_id, k_hops=2)
+
+            if not subgraph.get("goal"):
+                return f"# Goal Subgraph\n\nGoal `{goal_id}` not found."
+
+            goal = subgraph["goal"]
+            connected = subgraph.get("connected", [])
+
+            lines = [
+                f"# Goal: {goal.get('title', 'Untitled')}",
+                f"**ID:** `{goal_id}`",
+                f"**Status:** {goal.get('status', 'unknown')}",
+                f"**Priority:** {goal.get('priority', '-')}",
+            ]
+
+            if goal.get("description"):
+                lines.append(f"\n{goal['description']}")
+
+            if connected:
+                lines.append(f"\n## Connected Entities ({len(connected)} total)\n")
+
+                # Categorize connected nodes
+                for node in connected:
+                    if isinstance(node, dict):
+                        # Try to identify node type by properties
+                        if "approach" in node:
+                            lines.append(f"- **Strategy:** {node.get('title', 'Untitled')}")
+                        elif "severity" in node and "description" in node:
+                            lines.append(f"- **PainPoint:** {node.get('description', '')[:50]}...")
+                        elif "path" in node:
+                            lines.append(f"- **CodeArtifact:** `{node.get('path', '')}`")
+                        elif "criterion" in node:
+                            lines.append(f"- **AcceptanceCriteria:** {node.get('criterion', '')}")
+                        else:
+                            lines.append(f"- **Entity:** {node}")
+
+            return "\n".join(lines)
+
+        except Exception as e:
+            logger.error(f"Failed to get goal subgraph: {e}")
+            return f"# Error\n\nFailed to retrieve goal subgraph: {e}"
+
+    @mcp.resource("kg://projects/{project_id}/pain-points")
+    async def get_pain_points(project_id: str) -> str:
+        """
+        Get open pain points for a project.
+
+        Returns unresolved pain points sorted by severity.
+        """
+        logger.info(f"Resource requested: pain-points for project {project_id}")
+
+        try:
+            repo = get_repository()
+            pain_points = await repo.get_open_painpoints(project_id)
+
+            if not pain_points:
+                return f"# Open Pain Points for {project_id}\n\n✅ No open pain points!"
+
+            lines = [f"# Open Pain Points for {project_id}\n"]
+
+            severity_emoji = {
+                "critical": "🔴",
+                "high": "🟠",
+                "medium": "🟡",
+                "low": "🟢",
+            }
+
+            for pp in pain_points:
+                severity = pp.get("severity", "medium")
+                emoji = severity_emoji.get(severity, "⚪")
+                lines.append(f"## {emoji} [{severity.upper()}] Pain Point")
+                lines.append(f"**ID:** `{pp.get('id', 'N/A')}`")
+                lines.append(f"\n{pp.get('description', 'No description')}")
+
+                if pp.get("blocking_goals"):
+                    lines.append(f"\n**Blocking Goals:** {', '.join(pp['blocking_goals'])}")
+
+                lines.append("")
+
+            return "\n".join(lines)
+
+        except Exception as e:
+            logger.error(f"Failed to get pain points: {e}")
+            return f"# Error\n\nFailed to retrieve pain points: {e}"
+
+    logger.info("MCP resources registered successfully")