devhive 0.1.6__tar.gz

devhive-0.1.6/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: devhive
+Version: 0.1.6
+Summary: DevHive MCP Server
+Requires-Python: >=3.10

devhive-0.1.6/README.md

@@ -0,0 +1,224 @@
+# DevHive MCP Server
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![MCP Protocol](https://img.shields.io/badge/MCP-1.0-green)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**DevHive** is a powerful **Model Context Protocol (MCP)** server that orchestrates an autonomous AI software development team. It transforms a single LLM session into a sequential, multi-agent pipeline capable of handling complex software engineering tasks—from initial requirements analysis to final code archiving.
+
+Designed to integrate seamlessly with **OpenCode** and **GitHub Copilot**, DevHive provides the tooling and state management necessary for AI agents to work continuously on large projects without losing context.
+
+---
+
+## 🚀 Key Features
+
+*   **8-Stage Agent Pipeline:** A structured workflow guiding development through specialized roles:
+    1.  **Explorer:** Analyzes requirements and feasibility.
+    2.  **Proposal:** Creates detailed feature proposals.
+    3.  **Architect:** Designs technical architecture and system diagrams.
+    4.  **TaskPlanner:** Breaks down work into actionable developer tasks.
+    5.  **Developer:** Implements code and writes files.
+    6.  **QA:** Generates and executes test suites.
+    7.  **Auditor:** Verifies consistency against architecture and requirements.
+    8.  **Archivist:** Finalizes and archives the project state.
+*   **Persistent State Management:** Tracks project progress, artifacts, and file generation across sessions.
+*   **Context Optimization (RAG):** Built-in memory system using TF-IDF to retrieve relevant context from previous steps, reducing token usage and hallucination.
+*   **Cross-Platform CLI:** Easy-to-use command-line interface for configuration and server management.
+*   **Universal Compatibility:** Works as a local MCP server for OpenCode, Claude Desktop, or any MCP-compliant client.
+
+---
+
+## 🛠 Architecture
+
+DevHive operates on a strictly sequential pipeline model. Each agent produces a specific **Artifact** (JSON document) that serves as the input for the next agent.
+
+```mermaid
+graph LR
+    User[User Request] --> Explorer
+    Explorer --> Proposal
+    Proposal --> Architect
+    Architect --> TaskPlanner
+    TaskPlanner --> Developer
+    Developer --> QA
+    QA --> Auditor
+    Auditor --> Archivist
+    Archivist --> Done((Project Complete))
+```
+
+### Core Components
+
+*   **`mcp_server`**: The main Python package containing the server logic.
+*   **`TaskOrchestrator`**: Manages the transition between agents and validates outputs.
+*   **`MemoryStore`**: A local vector-lite store (TF-IDF) for semantic search over project history.
+*   **`ProjectStateManager`**: Persists project status to `project_state.json`.
+
+---
+
+## 📦 Installation
+
+### Prerequisites
+
+*   Python 3.10 or higher
+*   `pip`
+
+### Install from Source
+
+Clone the repository and install the package in editable mode:
+
+```bash
+git clone https://github.com/yourusername/devhive.git
+cd devhive
+pip install -e .
+```
+
+This installs the `devhive` CLI tool globally in your environment.
+
+---
+
+## ⚙️ Configuration
+
+DevHive includes a smart configuration tool that sets up your environment automatically.
+
+### 1. Run the Setup Wizard
+
+```bash
+devhive configure
+```
+
+The wizard will ask:
+*   **Client Selection:** OpenCode, GitHub Copilot (VS Code), or both.
+*   **MCP Server Registration:** For OpenCode users, it can automatically add the DevHive server to your `config.json`.
+*   **VS Code Integration:** For Copilot users, it injects the agent system prompts directly into your global VS Code settings (`github.copilot.chat.codeGeneration.instructions`).
+
+### 2. Manual Configuration (Optional)
+
+If you prefer manual setup:
+
+**OpenCode (`~/.config/opencode/opencode.json`):**
+```json
+{
+  "mcp": {
+    "devhive": {
+      "type": "local",
+      "command": ["python3", "-m", "mcp_server.server"],
+      "enabled": true,
+      "env": { "PYTHONUNBUFFERED": "1" }
+    }
+  }
+}
+```
+
+**VS Code (`settings.json`):**
+```json
+"github.copilot.chat.codeGeneration.instructions": [
+    {
+        "file": "/path/to/devhive/DEVHIVE_AGENT.md"
+    }
+]
+```
+
+---
+
+## 🖥 Usage
+
+### Starting the Server
+
+To start the MCP server locally (useful for debugging or manual connection):
+
+```bash
+devhive start
+```
+
+*Note: If configured correctly in OpenCode, the server starts automatically in the background.*
+
+### Workflow with AI Clients
+
+1.  **Open your AI Client** (OpenCode or VS Code Copilot).
+2.  **Initialize a Project:**
+    Ask the agent: *"Start a new pipeline for a CSV export feature."*
+    
+    The agent will use `devhive_start_pipeline`.
+3.  **Follow the Steps:**
+    The AI will automatically assume the role of the **Explorer**.
+    *   It will analyze the request.
+    *   It will submit its findings using `devhive_submit_result`.
+4.  **Iterate:**
+    DevHive will return the prompt for the next agent (Proposal). The AI client will switch roles and continue until the **Archivist** declares the project complete.
+
+---
+
+## 📚 API / Tool Reference
+
+The server exposes the following MCP tools to the AI agent:
+
+| Tool | Description |
+|------|-------------|
+| `devhive_start_pipeline` | Initializes a project and retrieves the first task (Explorer). |
+| `devhive_submit_result` | Submits work from the current agent, saves artifacts, and retrieves the next task. |
+| `devhive_search_memory` | Searches project history/context using semantic query. |
+| `devhive_get_recent_memories` | Retrieves the most recent interactions for context refreshment. |
+| `devhive_get_memory_stats` | Returns usage statistics for the project memory. |
+| `list_workspace_files` | Lists files in the current working directory. |
+| `read_workspace_file` | Reads content of a specific file. |
+
+---
+
+## 📂 Project Structure
+
+```text
+devhive/
+├── DEVHIVE_AGENT.md       # The "Brain" - System prompt for the AI agent
+├── AGENTS.md              # Documentation for agent roles
+├── pyproject.toml         # Python project configuration
+├── setup.py               # Legacy setup support
+├── mcp_server/            # Source code
+│   ├── agents/            # Logic for individual agents (Explorer, Developer, etc.)
+│   ├── core/              # Core infrastructure (LLM, Memory, State)
+│   ├── utils/             # Filesystem and validation utilities
+│   ├── cli.py             # CLI implementation (devhive command)
+│   └── server.py          # FastMCP server entry point
+└── tests/                 # Test suite
+```
+
+---
+
+## 🧪 Development
+
+### Running Tests
+
+DevHive uses `pytest` for testing.
+
+```bash
+# Install test dependencies
+pip install pytest
+
+# Run all tests
+pytest
+```
+
+### Adding a New Agent
+
+1.  Create a new class in `mcp_server/agents/` inheriting from `BaseAgent`.
+2.  Define the agent's specific validation logic in `mcp_server/utils/validation.py`.
+3.  Register the agent in `mcp_server/server.py` and `mcp_server/core/task_orchestrator.py`.
+4.  Update `DEVHIVE_AGENT.md` to include the new role in the pipeline instructions.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1.  Fork the repository.
+2.  Create a feature branch (`git checkout -b feature/amazing-feature`).
+3.  Commit your changes (`git commit -m 'Add some amazing feature'`).
+4.  Push to the branch (`git push origin feature/amazing-feature`).
+5.  Open a Pull Request.
+
+Please ensure all tests pass and your code follows the existing style conventions (Python 3.10+ type hinting).
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

devhive-0.1.6/devhive.egg-info/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: devhive
+Version: 0.1.6
+Summary: DevHive MCP Server
+Requires-Python: >=3.10

devhive-0.1.6/devhive.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+setup.py
+devhive.egg-info/PKG-INFO
+devhive.egg-info/SOURCES.txt
+devhive.egg-info/dependency_links.txt
+devhive.egg-info/entry_points.txt
+devhive.egg-info/top_level.txt
+mcp_server/__init__.py
+mcp_server/cli.py
+mcp_server/server.py
+mcp_server/agents/__init__.py
+mcp_server/agents/architect.py
+mcp_server/agents/archivist.py
+mcp_server/agents/auditor.py
+mcp_server/agents/base_agent.py
+mcp_server/agents/ceo.py
+mcp_server/agents/developer.py
+mcp_server/agents/explorer.py
+mcp_server/agents/proposal.py
+mcp_server/agents/qa.py
+mcp_server/agents/task_agent.py

devhive-0.1.6/devhive.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

devhive-0.1.6/devhive.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+devhive = mcp_server.cli:main
+devhive_mcp = mcp_server.server:main

devhive-0.1.6/devhive.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_server

devhive-0.1.6/mcp_server/__init__.py

@@ -0,0 +1 @@
+# MCP Server Package

devhive-0.1.6/mcp_server/agents/__init__.py

@@ -0,0 +1,10 @@
+from mcp_server.agents.base_agent import BaseAgent
+from mcp_server.agents.explorer import ExplorerAgent
+from mcp_server.agents.proposal import ProposalAgent
+from mcp_server.agents.architect import ArchitectAgent
+from mcp_server.agents.task_agent import TaskAgent
+from mcp_server.agents.developer import DeveloperAgent
+from mcp_server.agents.qa import QAAgent
+from mcp_server.agents.auditor import AuditorAgent
+from mcp_server.agents.archivist import ArchivistAgent
+from mcp_server.agents.ceo import CEOAgent

devhive-0.1.6/mcp_server/agents/architect.py

@@ -0,0 +1,28 @@
+import json
+from typing import Dict, Any
+from mcp.server.fastmcp import Context
+from mcp_server.agents.base_agent import BaseAgent
+
+class ArchitectAgent(BaseAgent):
+    role = "Architect"
+    
+    async def execute(self, ctx: Context, **kwargs) -> str:
+        context = self.get_context()
+        sys_prompt = "You are the Tech Lead. Output JSON only."
+        user_prompt = f"""Design architecture.
+Context: {json.dumps(context, default=str)}
+Return JSON with keys: architecture_pattern, components, data_models, apis."""
+        
+        resp = await self._call_llm(ctx, sys_prompt, user_prompt)
+        data = self._parse_json(resp)
+        return self.save_artifact("architecture", data)
+    
+    def generate_summary(self, data: Dict[str, Any]) -> str:
+        """Generate executive summary for Architect agent."""
+        components_count = len(data.get("components", []))
+        apis_count = len(data.get("apis", []))
+        pattern = data.get("architecture_pattern", "N/A")
+        return (
+            f"Designed architecture using {pattern} pattern "
+            f"with {components_count} components and {apis_count} APIs."
+        )

devhive-0.1.6/mcp_server/agents/archivist.py

@@ -0,0 +1,19 @@
+import json
+from typing import Dict, Any
+from mcp.server.fastmcp import Context
+from mcp_server.agents.base_agent import BaseAgent
+
+class ArchivistAgent(BaseAgent):
+    role = "Archivist"
+    async def execute(self, ctx: Context, **kwargs) -> str:
+        state = self.state_manager.get_state()
+        state["status"] = "completed"
+        if "artifacts" not in state: state["artifacts"] = {}
+        state["artifacts"]["archive"] = "archived"
+        self.state_manager.update_state(state)
+        return "Project Archived Successfully"
+    
+    def generate_summary(self, data: Dict[str, Any]) -> str:
+        """Generate executive summary for Archivist agent."""
+        # Archivist doesn't use structured data, just returns success message
+        return "Project archived successfully. All artifacts and state preserved."

devhive-0.1.6/mcp_server/agents/auditor.py

@@ -0,0 +1,28 @@
+import json
+from typing import Dict, Any
+from mcp.server.fastmcp import Context
+from mcp_server.agents.base_agent import BaseAgent
+
+class AuditorAgent(BaseAgent):
+    role = "Auditor"
+    async def execute(self, ctx: Context, **kwargs) -> str:
+        context = self.get_context()
+        sys_prompt = "You are the Auditor. Output JSON only."
+        user_prompt = f"""Verify the project.
+Context: {json.dumps(context, default=str)}
+Return JSON with keys: architecture_consistency (bool), missing_pieces (list), security_risks (list)."""
+        
+        resp = await self._call_llm(ctx, sys_prompt, user_prompt)
+        data = self._parse_json(resp)
+        return self.save_artifact("verification", data)
+    
+    def generate_summary(self, data: Dict[str, Any]) -> str:
+        """Generate executive summary for Auditor agent."""
+        consistent = data.get("architecture_consistency", False)
+        missing_count = len(data.get("missing_pieces", []))
+        security_count = len(data.get("security_risks", []))
+        status = "✓ Passed" if consistent and missing_count == 0 else "⚠ Issues Found"
+        return (
+            f"{status}. Missing pieces: {missing_count}, "
+            f"Security risks: {security_count}"
+        )

devhive-0.1.6/mcp_server/agents/base_agent.py

@@ -0,0 +1,104 @@
+import json
+import logging
+from typing import Dict, Any, Optional
+from mcp.types import SamplingMessage, TextContent
+from mcp.server.fastmcp import Context
+from mcp_server.core.project_state_manager import ProjectStateManager
+from mcp_server.core.artifact_manager import ArtifactManager
+from mcp_server.core.context_router import ContextRouter
+from mcp_server.core.llm import LLM
+
+logger = logging.getLogger(__name__)
+
+class BaseAgent:
+    role: str = "Base"
+
+    def __init__(self, project_name: str):
+        self.project_name = project_name
+        self.state_manager = ProjectStateManager(project_name)
+        self.artifact_manager = ArtifactManager(project_name)
+        self.context_router = ContextRouter(self.state_manager, self.artifact_manager)
+
+    def get_context(self) -> Dict[str, Any]:
+        return self.context_router.get_context(self.role)
+
+    def save_artifact(self, step_name: str, content: Dict[str, Any]) -> str:
+        aid = self.artifact_manager.save_artifact(step_name, content)
+        self.state_manager.update_artifact(step_name, aid)
+        return aid
+    
+    def generate_summary(self, data: Dict[str, Any]) -> str:
+        """
+        Generate a 1-3 sentence executive summary of the agent's work.
+        
+        This default implementation provides a basic summary. Subclasses should
+        override this method to provide more specific summaries based on their
+        role and the data they produce.
+        
+        Args:
+            data: The artifact data produced by the agent
+        
+        Returns:
+            A concise 1-3 sentence summary suitable for orchestrator context
+        """
+        return f"{self.role} completed successfully."
+
+    async def _call_llm(self, ctx: Context, system_prompt: str, user_prompt: str, max_tokens: int = 2000)-> str:
+        decision = await LLM.generate_json(
+            ctx,
+            system_prompt,
+            user_prompt
+        )
+        return json.dumps(decision)
+
+
+    async def _call_llm_old(self, ctx: Context, system_prompt: str, user_prompt: str, max_tokens: int = 2000) -> str:
+        """Helper to call LLM via Sampling."""
+        try:
+            messages = [
+                {"role": "user", "content": { "type": "text", "text": f"{system_prompt}\n\n{user_prompt}" }}
+            ]
+            
+            # Using create_message which is standard
+            if hasattr(ctx.session, 'create_message'):
+                try:
+                    result = await ctx.session.create_message(
+                        messages=messages,
+                        max_tokens=max_tokens,
+                        system_prompt=system_prompt
+                    )
+                except:
+                    # Retry with just user prompt if system prompt arg fails
+                    result = await ctx.session.create_message(
+                        messages=messages,
+                        max_tokens=max_tokens
+                    )
+
+                if hasattr(result, 'content') and hasattr(result.content, 'text'):
+                    return result.content.text
+                return str(result)
+            
+            # Fallback
+            if hasattr(ctx.session, 'sample'):
+                 return str(await ctx.session.sample(messages=messages, max_tokens=max_tokens))
+            
+            return '{"error": "No sampling capability found on session"}'
+
+        except Exception as e:
+            logger.error(f"LLM Call failed: {e}")
+            return json.dumps({"error": str(e)})
+
+    def _parse_json(self, text: str) -> Dict[str, Any]:
+        """ Robust JSON parser """
+        text = text.strip()
+        if "```json" in text:
+            text = text.split("```json")[1].split("```")[0]
+        elif "```" in text:
+            text = text.split("```")[1].split("```")[0]
+        try:
+            return json.loads(text)
+        except:
+            return {"raw_text": text}
+
+    async def execute(self, ctx: Context, **kwargs) -> Any:
+        raise NotImplementedError

devhive-0.1.6/mcp_server/agents/ceo.py

@@ -0,0 +1,171 @@
+import json
+from typing import Dict, Any
+from mcp.server.fastmcp import Context
+from mcp_server.agents.base_agent import BaseAgent
+from mcp_server.core.project_state_manager import ProjectStateManager
+
+class CEOAgent(BaseAgent):
+    role = "CEO"
+    
+    def get_next_agent_deterministic(self) -> Dict[str, Any]:
+        """
+        Determine next agent to run based on current state (no LLM needed).
+        This is a rule-based decision making process following the strict pipeline sequence.
+        
+        Pipeline order:
+        1. Explorer
+        2. Proposal
+        3. Architect
+        4. TaskPlanner
+        5. Developer
+        6. QA
+        7. Auditor
+        8. Archivist
+        
+        Returns:
+            Dict with 'agent' (role name) and 'reason' (explanation)
+        """
+        state = self.state_manager.get_state()
+        artifacts = state.get("artifacts", {})
+        
+        # Check each stage in order
+        if artifacts.get("exploration") is None:
+            return {
+                "agent": "Explorer",
+                "reason": "Need initial feature analysis and exploration"
+            }
+            
+        # Determine complexity from exploration artifact
+        complexity = "high" # Default to high safety
+        try:
+            expl_id = artifacts.get("exploration")
+            if expl_id:
+                expl_data = self.artifact_manager.load_artifact(expl_id)
+                complexity = expl_data.get("complexity", "high").lower()
+        except Exception:
+            pass # Fallback to high complexity on error
+        
+        # Dynamic Routing based on Complexity
+        # Low: Explorer -> Developer -> QA -> Archivist
+        # Medium: Explorer -> Proposal -> Developer -> QA -> Archivist
+        # High: Full Suite
+        
+        if artifacts.get("proposal") is None:
+            if complexity == "low":
+                pass # Skip Proposal
+            else:
+                return {
+                    "agent": "Proposal",
+                    "reason": "Exploration complete, need feature proposal"
+                }
+        
+        if artifacts.get("architecture") is None:
+            if complexity in ["low", "medium"]:
+                pass # Skip Architecture
+            else:
+                return {
+                    "agent": "Architect",
+                    "reason": "Proposal complete, need technical architecture design"
+                }
+        
+        if artifacts.get("tasks") is None:
+            if complexity in ["low", "medium"]:
+                pass # Skip Task Planning
+            else:
+                return {
+                    "agent": "TaskPlanner",
+                    "reason": "Architecture complete, need task breakdown"
+                }
+        
+        if artifacts.get("implementation") is None:
+            return {
+                "agent": "Developer",
+                "reason": "Ready for implementation"
+            }
+        
+        if artifacts.get("tests") is None:
+            return {
+                "agent": "QA",
+                "reason": "Implementation complete, need tests"
+            }
+        
+        if artifacts.get("verification") is None:
+            if complexity in ["low", "medium"]:
+                pass # Skip Auditor
+            else:
+                return {
+                    "agent": "Auditor",
+                    "reason": "Tests complete, need final verification"
+                }
+        
+        if artifacts.get("archive") is None:
+            return {
+                "agent": "Archivist",
+                "reason": "All stages complete, ready to archive project"
+            }
+        
+        # All done
+        return {
+            "agent": "Complete",
+            "reason": "All pipeline stages finished, project is complete"
+        }
+    
+    async def execute(self, ctx: Context, **kwargs) -> Dict[str, Any]:
+        """
+        Original LLM-based decision making (requires sampling support).
+        Currently not used in manual workflow.
+        """
+        state_manager = ProjectStateManager(self.project_name)
+        state = state_manager.get_state()
+
+        context = {
+            "project_status": state.get('status'),
+            "artifacts_summary": state.get("artifacts", {})
+        }
+
+        sys_prompt = """
+        You are the CEO orchestrating an AI software development pipeline.
+
+        The pipeline is strictly sequential:
+
+        1 Explorer
+        2 Proposal
+        3 Architect
+        4 TaskPlanner
+        5 Developer
+        6 QA
+        7 Auditor
+        8 Archivist
+
+        Rules:
+
+        - NEVER return Wait unless the pipeline is finished
+        - ALWAYS select the next missing role
+        - Each role produces an artifact
+
+        Explorer → exploration
+        Proposal → proposal
+        Architect → architecture
+        TaskPlanner → tasks
+        Developer → implementation
+        QA → tests
+        Auditor → verification
+        Archivist → archived
+
+        Return JSON only:
+        { "decision": "Run <Role>", "reason": "..." }
+        """
+        user_prompt = f"""Decide next step.
+
+Project: {context.get('project_name')}
+Status: {context.get('project_status')}
+Stage: {context.get('stage')}
+Artifacts: {json.dumps(context.get('artifacts_summary', {}), indent=2)}
+
+Available Roles: Explorer, Proposal, Architect, TaskPlanner, Developer, QA, Auditor, Archivist.
+Return JSON: {{ "decision": "Run <Role>", "reason": "..." }}
+If finished, "Run Archivist".
+If stage is "initialization", "Run Explorer"
+"""
+        resp = await self._call_llm(ctx, sys_prompt, user_prompt)
+        return self._parse_json(resp)

devhive-0.1.6/mcp_server/agents/developer.py

@@ -0,0 +1,44 @@
+import json
+from typing import Dict, Any
+from mcp.server.fastmcp import Context
+from mcp_server.agents.base_agent import BaseAgent
+
+class DeveloperAgent(BaseAgent):
+    role = "Developer"
+    
+    def write_files(self, data: Dict[str, Any]) -> list[str]:
+        """Write implementation files to disk. Returns list of file paths."""
+        files = data.get("files", [])
+        from mcp_server.utils.filesystem import write_file
+        file_paths = []
+        for f in files:
+            if isinstance(f, dict) and "path" in f and "content" in f:
+                write_file(f["path"], f["content"])
+                file_paths.append(f["path"])
+        return file_paths
+    
+    async def execute(self, ctx: Context, **kwargs) -> str:
+        context = self.get_context()
+        sys_prompt = "You are the Developer. Output JSON only."
+        user_prompt = f"""Implement the feature.
+Context: {json.dumps(context, default=str)}
+Return JSON with keys: implementation_strategy, file_structure, pseudocode, files (list of {{path, content}})."""
+        
+        resp = await self._call_llm(ctx, sys_prompt, user_prompt, max_tokens=4000)
+        data = self._parse_json(resp)
+        
+        # Write files (using extracted method)
+        file_paths = self.write_files(data)
+        self.state_manager.add_files(file_paths)
+        return self.save_artifact("implementation", data)
+    
+    def generate_summary(self, data: Dict[str, Any]) -> str:
+        """Generate executive summary for Developer agent."""
+        files_count = len(data.get("files", []))
+        strategy = data.get("implementation_strategy", "N/A")
+        # Truncate if too long
+        if len(strategy) > 80:
+            strategy = strategy[:80] + "..."
+        return (
+            f"Implemented {files_count} files using strategy: {strategy}"
+        )