Content
<p align="center"><img src="chungoid.png" alt="Chungoid Banner"></p>
# Chungoid MCP Server
This project implements the Chungoid Model Context Protocol (MCP) Server, designed to orchestrate a stage-based workflow for bootstrapping new software projects via interactions with an AI agent (like Cursor).
## Overview
The ultimate goal is to automate the initial, often repetitive, steps of setting up a new project structure according to a defined process. ***Notably, a significant portion of this server's own codebase, including its core logic and utilities, was bootstrapped using the very stage-based workflow it orchestrates, demonstrating the process in action.***
The server listens for MCP requests over **stdio** and manages a predefined sequence of development stages (Stages 0-7.5). It uses state tracking (`project_status.json`), stage-specific prompts (`.chungoid/templates/stages/`), and core logic modules to guide the AI through tasks like planning, code generation, testing, and documentation.
## Architecture
The server is built using Python and leverages the `fastmcp` library for handling MCP communication.
**Key Components:**
* **`chungoidmcp.py`:** The main entry point, initializing the `FastMCP` server with **stdio transport**, registering tools, and handling the main execution loop.
* **`stage_executor.py`:** Contains the core logic for identifying the current stage, loading relevant prompts, executing stage-specific actions (which might involve calling other modules or running external tools via `ToolAdapter`), and preparing results.
* **`utils/state_manager.py`:** Manages the project's progress by reading and writing stage status to `project_status.json`, ensuring sequential execution and handling file locking.
* **`utils/prompt_manager.py`:** Loads the core orchestration prompt (`templates/build-prompt.txt`) and stage-specific prompts (`.chungoid/templates/stages/stage<N>.txt`).
* **`utils/logger_setup.py`:** Configures structured logging (JSON format) to a file.
* **`utils/tool_adapters.py`:** (Placeholder/Design) Provides mechanisms for the `StageExecutor` to securely run external tools or commands defined in a schema (`dev-docs/tools/tools_schema.json`).
* **`decision_framework.py`:** (Placeholder/Basic Implementation) Encapsulates higher-level logic, configuration management, and potential extensibility points.
* **`application_security.py`:** (Placeholder) Contains stubs for security functions like input validation, path sanitization, and safer subprocess execution.
* **`dev-docs/`:** Contains all design documents, plans, reports, and analysis generated during the workflow. Within the `analysis` sub-directory, `feelings.json` stores structured reflections on each stage's execution and prompt performance.
## Setup
1. **Prerequisites:**
* Python 3.10+
* Git
2. **Clone Repository:**
```bash
git clone <repository_url>
cd chungoid-mcp
```
3. **Create Virtual Environment:**
```bash
python -m venv .venv
source .venv/bin/activate # Linux/macOS
# .\.venv\Scripts\activate # Windows
```
4. **Install Dependencies:**
```bash
pip install -r requirements.txt
```
5. **Configure Environment:**
* Ensure `.env` exists or create it (potentially from `.env.example` if one is provided later).
* Verify environment variables like `LOG_FILE_PATH`, `STATUS_FILE_PATH`, and prompt directories are set correctly (or rely on defaults in `chungoidmcp.py`).
## Usage
**Important:** This server is designed to be launched **by an MCP client (like Cursor)** using stdio transport, not run manually from the terminal.
1. **Configure Your MCP Client (e.g., Cursor):**
* Open your client's MCP server configuration (e.g., `~/.cursor/mcp.json~`, or the settings UI).
* Add or update an entry for this server. Use a descriptive name (e.g., `"chungoid"`).
* Specify the **absolute path** command to launch the server using the Python interpreter **from the Chungoid virtual environment** and the **absolute path** to `chungoidmcp.py` within the Chungoid installation.
* Set the transport type to `stdio`.
* Crucially, ensure the `workingDirectory` is set to the **absolute path of the TARGET PROJECT directory** that Chungoid is intended to build or manage.
**Example Cursor Configuration (`~/.cursor/mcp.json` or similar):**
```json
{
"mcpServers": {
"chungoid": {
"command": "/full/path/to/chungoid-mcp/.venv/bin/python3",
"args": [
"/full/path/to/chungoid-mcp/chungoidmcp.py"
],
"transport": "stdio",
"workingDirectory": "/full/path/to/your/TARGET_PROJECT_DIRECTORY"
}
}
}
```
* *(Replace `/full/path/to/chungoid-mcp` with the Chungoid installation path)*
* *(Replace `/full/path/to/your/TARGET_PROJECT_DIRECTORY` with the path to the project you are building)*
* Restart your MCP client if necessary for the settings to take effect.
2. **Interaction:**
* Connect to the server (e.g., `chungoid`) from within your MCP client.
* The client will launch the `chungoidmcp.py` script and communicate via stdio.
* **Key Tools:**
* `get_project_status`: Retrieves the current status of all stages.
* `execute_next_stage`: Triggers the execution logic for the next pending stage based on `project_status.json`.
## Development
* **Project Structure:** Refer to the `PROJECT-STRUCTURE` section in `dev-docs/architecture/blueprint.txt` for a detailed directory layout.
* **Linting:** Uses `ruff` and `pylint`. Check code with:
```bash
ruff check .
pylint chungoidmcp.py stage_executor.py utils/ decision_framework.py application_security.py
```
* **Formatting:** Uses `black`. Format code with:
```bash
black .
```
* **Testing:** Uses `pytest`. Run tests with:
```bash
pytest
```
(Currently tests `decision_test.py` and `security_tests.py`).
* **Documentation:** Project documentation (plans, reports, etc.) resides in `dev-docs/`.
