**Product Requirements Document: Lamplighter-MCP**

**Version:** 1.0
**Date:** 2025-04-13

**1. Introduction**

Lamplighter-MCP is a backend service designed to act as an intelligent context engine for software development teams using AI coding assistants like Cursor, particularly within large and complex codebases. It addresses the challenges of providing relevant, up-to-date project context (code structure, feature specifications, task status) to AI models and developers, and automates the breakdown of large feature specifications into manageable tasks. It operates exclusively through the Model Context Protocol (MCP) for seamless integration with compatible tools. The project draws thematic inspiration from "The Little Prince," specifically the Lamplighter character, symbolizing guidance and dutiful tracking.

**2. Goals**

*   **Improve AI Assistant Effectiveness:** Provide focused, structured, and relevant context from the codebase and ongoing tasks to AI coding assistants (like Cursor) via MCP, enhancing their understanding and code generation quality within large projects.
*   **Automate Task Breakdown:** Automatically process high-level feature specifications (from Confluence) using AI, breaking them down into smaller, actionable development tasks documented in Markdown.
*   **Streamline Developer Workflow:** Integrate task management directly into the AI-assisted coding environment, reducing context switching and manual tracking overhead. Facilitate a smooth flow from specification to task execution.
*   **Maintain Living Project Documentation:** Generate and maintain useful Markdown-based documentation (codebase summary, task lists, history log) as a by-product of the system's operation, benefiting both AI and human developers.
*   **Provide Centralized Context:** Act as a single source of truth for key project context elements accessible via the MCP interface.

**3. Target Audience**

*   Software developers within the company using AI coding assistants (specifically Cursor) for feature implementation and code generation.
*   Teams working on large codebases where maintaining context for AI tools is challenging.
*   Teams following a workflow where feature specifications originate in Confluence.

**4. Functional Requirements**

*   **FR1: Codebase Analysis**
    *   The system MUST provide an MCP tool (`analyze_codebase`) that analyzes the project's codebase structure.
    *   This analysis SHOULD identify key directories, modules, reusable components, primary technologies/frameworks.
    *   The analysis results MUST be used to generate/overwrite a structured `codebase_summary.md` file in the designated context directory.
    *   *(Optional)* The analysis MAY leverage AI via the `AIService` to generate summaries for complex code sections.
*   **FR2: Confluence Specification Processing**
    *   The system MUST provide an MCP tool (`process_confluence_spec`) that accepts a Confluence page URL/ID as input.
    *   The tool MUST securely fetch the content from the specified Confluence page.
    *   The tool MUST utilize the configured AI model (via `AIService`) to process the fetched specification text.
    *   The AI processing MUST break down the specification into a checklist of actionable development tasks, referencing relevant modules identified in `codebase_summary.md`.
    *   The output MUST be saved as a new Markdown file (e.g., `feature_tasks/feature_XYZ_tasks.md`) in the designated context directory.
*   **FR3: Task Status Management (Markdown-based)**
    *   The system MUST provide an MCP tool (`update_task_status`) to modify the status of a task within a feature's Markdown file.
    *   Inputs MUST include identifiers for the feature and the specific task (e.g., feature name, task description text or ID), and the desired new status (e.g., 'ToDo', 'InProgress', 'Done').
    *   The tool MUST parse the relevant `feature_tasks/*.md` file, locate the task checklist item, update its status marker (e.g., `- [ ]` to `- [x]`), and rewrite the file.
*   **FR4: Task Suggestion**
    *   The system MUST provide an MCP tool (`suggest_next_task`) that identifies and returns the next actionable task (typically the first task marked 'ToDo') from a specified feature's Markdown file.
*   **FR5: History Logging**
    *   The system MUST maintain an append-only `history_log.md` file in the context directory.
    *   Key actions performed via MCP tools (e.g., codebase analysis completion, spec processing, task status update) MUST trigger an entry in the log, timestamped, describing the event.
*   **FR6: Context Provision via MCP**
    *   The system MUST provide MCP tools (e.g., `get_codebase_summary`, `get_history_log`, `get_feature_tasks`) to allow the MCP client (Cursor) to retrieve the content of the managed Markdown context files.
*   **FR7: AI-Assisted Task Completion Workflow**
    *   The system MUST support the "AI Suggestion + User Confirmation" workflow for marking tasks complete within Cursor.
    *   This requires appropriate MCP tool (`update_task_status`) implementation and assumes guiding rules are provided to Cursor (via `.cursor/rules/`) instructing the AI to:
        *   Attempt task implementation as requested by the user.
        *   Upon believing the task is implemented, *propose* using the `update_task_status` tool.
        *   Extract necessary identifiers (task, feature).
        *   Wait for explicit user confirmation (e.g., "Yes").
        *   Only execute the `update_task_status` tool upon confirmation.

**5. Non-Functional Requirements**

*   **NFR1: Usability (Cursor Integration):** Seamless and intuitive interaction via Cursor is paramount. This relies heavily on well-defined MCP tools and comprehensive rule files (`.cursor/rules/*.mdc`) guiding the AI's behavior and tool usage.
*   **NFR2: AI Model Flexibility:** The system MUST be designed to interact with different LLM providers (e.g., OpenAI, Google Gemini) through a dedicated, abstracted `AIService` module. Configuration should allow easy switching between configured providers/models.
*   **NFR3: Maintainability:** The system MUST have a modular architecture, clearly separating core logic (analysis, processing, task management) from the MCP interface layer.
*   **NFR4: Security:** API keys and tokens (Confluence, LLMs) MUST be handled securely (e.g., via environment variables or a secrets management system), not hardcoded.
*   **NFR5: Reliability:** The MCP server should handle errors gracefully (e.g., failure to fetch from Confluence, LLM API errors, file access issues) and provide informative error messages back to the MCP client where appropriate.
*   **NFR6: Data Format:** The primary state and context MUST be stored and managed using structured Markdown files within a defined directory structure.

**6. Interface Requirements**

*   **IF1: Primary Interface:** The *only* programmatic interface to Lamplighter-MCP MUST be via the Model Context Protocol (MCP).
*   **IF2: MCP Tools:** The MCP server MUST expose tools including, but not limited to:
    *   `analyze_codebase`
    *   `process_confluence_spec` (args: `confluence_url`)
    *   `update_task_status` (args: `feature_identifier`, `task_identifier`, `new_status`)
    *   `suggest_next_task` (args: `feature_identifier`)
    *   `get_codebase_summary`
    *   `get_history_log`
    *   `get_feature_tasks` (args: `feature_identifier`)
*   **IF3: Cursor Configuration:** The project using Lamplighter-MCP MUST include a `.cursor/` directory containing:
    *   `mcp.json`: Configuring Cursor to connect to the Lamplighter-MCP server and defining the available tools.
    *   `rules/*.mdc`: Markdown rule files providing context to Cursor about the system's purpose, the structure of the Markdown context files, detailed instructions on how and when to use each MCP tool, and guidance for specific workflows (like task completion confirmation).

**7. Data Management**

*   **DM1: Context Directory:** All managed context MUST reside within a designated directory (e.g., `lamplighter_context/`) within the project repository.
*   **DM2: Markdown File Structure:** The context directory MUST contain the following Markdown files:
    *   `project_overview.md` (Manually created/updated)
    *   `codebase_summary.md` (Generated/Managed by Lamplighter-MCP)
    *   `feature_tasks/` (Directory containing `feature_XYZ_tasks.md` files, generated/managed by Lamplighter-MCP)
    *   `history_log.md` (Append-only, managed by Lamplighter-MCP)
    *   `developer_preferences.md` (Optional, manual)
*   **DM3: Data Persistence:** The primary persistence mechanism is the filesystem (the Markdown files), intended to be version-controlled with the project code (e.g., using Git).

**8. AI Requirements**

*   **AI1: Core Functionality:** AI (LLMs) is essential for the `process_confluence_spec` functionality (task breakdown).
*   **AI2: Agnostic Service:** An `AIService` module MUST abstract interactions with different LLM providers.
*   **AI3: Configurability:** Users must be able to configure which AI provider and model Lamplighter-MCP uses via secure configuration methods.

**9. Dependencies**

*   Confluence API (for reading specifications)
*   LLM APIs (e.g., OpenAI API, Google AI API)
*   MCP Client implementation (provided by Cursor)
*   Runtime environment (e.g., Node.js, Python)
*   Filesystem access

**10. Out of Scope**

*   Command Line Interface (CLI)
*   Standalone Graphical User Interface (GUI)
*   Real-time collaboration features (beyond storing state in version-controlled files)
*   Direct integration with CI/CD pipelines (though generated files can be used by them)
*   Running code analysis linters or tests directly (focus is on structural analysis for context).

---