lamplighter-mcp/documents/tasks.md

An intelligent context engine for AI-assisted software development

# Lamplighter-MCP Implementation Tasks

## Phase 1: Project Setup & Core Infrastructure

*   [x] **Initialize Project:**
    *   [x] Set up Node.js project (`npm init`).
    *   [x] Initialize TypeScript (`npm install --save-dev typescript @types/node`, `npx tsc --init`).
    *   [x] Configure `tsconfig.json` (target ESNext/ES2020+, moduleResolution NodeNext/Node16, outDir, rootDir, etc.).
    *   [x] Set up `package.json` scripts (`build`, `start`, `dev`).
*   [x] **Install Core Dependencies:**
    *   [x] Install MCP SDK: `npm install @modelcontextprotocol/sdk`
    *   [x] Install Zod (peer dependency for SDK): `npm install zod`
    *   [x] Install Express for HTTP/SSE transport: `npm install express @types/express`
    *   [x] Install DotEnv for configuration: `npm install dotenv`
    *   [x] Install HTTP client: `npm install axios`
    *   [x] Install LLM SDKs (choose initial): `npm install openai` and/or `npm install @google-ai/generativelanguage`
*   [x] **Establish Directory Structure:**
    *   [x] Create `src/` directory for source code.
    *   [x] Create `src/modules/` for core logic modules.
    *   [x] Create `src/services/` for external service integrations (like AI).
    *   [x] Create `src/server.ts` as the main server entry point.
    *   [x] Create placeholder `lamplighter_context/` directory at the project root.
    *   [x] Create `.cursor/` directory at the project root.
*   [x] **Setup Configuration:**
    *   [x] Create `.env.example` file listing all required environment variables (API keys, Confluence URL, AI provider/model, Context Dir Path, Port).
    *   [x] Implement loading environment variables using `dotenv` early in the application startup.
*   [x] **Implement Basic HTTP/SSE Server:**
    *   [x] Set up basic Express app in `src/server.ts`.
    *   [x] Implement `/sse` endpoint using `SSEServerTransport`.
    *   [x] Implement `/messages` endpoint using `SSEServerTransport`.
    *   [x] Implement multi-client connection management using `sessionId` map.
    *   [x] Initialize basic `McpServer` instance.
    *   [x] Connect `McpServer` to transports in the `/sse` handler.
    *   [x] Add basic start script to run the compiled server (`node dist/server.js`).

## Phase 2: Core Logic Modules Implementation

*   [x] **Implement `AIService` (`src/services/aiService.ts`):**
    *   [x] Define `IAIService` interface or `BaseAIService` class.
    *   [x] Implement `generateText` method with provider selection logic based on config/env vars.
    *   [x] Implement concrete class for initial LLM provider (e.g., `OpenAIService`) handling API call and response.
    *   [x] Securely load API keys from environment variables.
*   [x] **Implement `ConfluenceReader` (`src/modules/confluenceReader.ts`):**
    *   [x] Implement `fetchPageContent` using `axios`.
    *   [x] Handle authentication using Confluence API token from env vars.
    *   [x] Implement basic error handling for API requests.
    *   [x] Perform basic extraction of relevant text content from the response if necessary.
*   [x] **Implement `HistoryLogger` (`src/modules/historyLogger.ts`):**
    *   [x] Implement `log` method.
    *   [x] Ensure correct timestamp formatting (`[YYYY-MM-DD HH:MM:SS]`).
    *   [x] Use `fs.appendFile` for efficient appending.
    *   [x] Ensure correct path resolution to `history_log.md`.
*   [x] **Implement `CodebaseAnalyzer` (`src/modules/codebaseAnalyzer.ts`):**
    *   [x] Implement `analyze` method.
    *   [x] *Initial Version:* Implement basic directory traversal using `fs.readdir` / `fs.stat`. Identify files/folders. Detect basic tech (e.g., check for `package.json`, `pom.xml`).
    *   [x] Implement generation of basic Markdown structure for `codebase_summary.md`.
    *   [x] Implement writing the generated content to `codebase_summary.md` using `fs.writeFile`.
    *   [x] *(Future)* Integrate more advanced tools (`tree-sitter`, etc.) if needed.
*   [x] **Implement `FeatureSpecProcessor` (`src/modules/featureSpecProcessor.ts`):**
    *   [x] Implement `processSpecification` method.
    *   [x] Implement prompt construction logic, including spec text and relevant parts of `codebase_summary.md`.
    *   [x] Call `AIService.generateText`.
    *   [x] Implement parsing of LLM response (expecting Markdown checklist). Handle potential variations/errors in LLM output.
    *   [x] Implement `deriveFeatureId` helper function (e.g., sanitize Confluence title or use page ID).
    *   [x] Implement writing the final task list to `feature_tasks/feature_XYZ_tasks.md`.
*   [x] **Implement `TaskManager` (`src/modules/taskManager.ts`):**
    *   [x] **Implement Markdown Parsing/Updating Logic (Core Challenge):**
        *   [x] Develop a robust function to read a feature task file and parse lines into structured task objects (e.g., `{ text: string, status: 'ToDo' | 'Done' }`).
        *   [x] Develop logic within `updateTaskStatus` to find the target task (initially by exact text match) and update its status marker (`- [ ]` <-> `- [x]`) *in the original file content string or buffer*.
        *   [x] Ensure the entire file is rewritten correctly after modification.
    *   [x] Implement `updateTaskStatus` method incorporating the parsing/updating logic.
    *   [x] Implement `suggestNextTask` method using the parsing logic to find the first task with status 'ToDo'.

## Phase 3: MCP Tool Implementation & Integration

*   [x] **Define & Implement `analyze_codebase` Tool:**
    *   [x] Define with `server.tool()` in `src/server.ts`.
    *   [x] Implement handler calling `codebaseAnalyzer.analyze()`.
    *   [x] Add call to `historyLogger.log()`.
    *   [x] Implement basic error handling (`try/catch`) and return appropriate MCP response.
*   [x] **Define & Implement `process_confluence_spec` Tool:**
    *   [x] Define with `server.tool()`, including `zod` schema for `confluence_url`.
    *   [x] Implement handler calling `confluenceReader`, reading `codebase_summary.md`, calling `featureSpecProcessor`.
    *   [x] Add call to `historyLogger.log()`.
    *   [x] Implement error handling (`try/catch`) and return appropriate MCP response.
*   [x] **Define & Implement `update_task_status` Tool:**
    *   [x] Define with `server.tool()`, including `zod` schema for `feature_identifier`, `task_identifier`, `new_status`.
    *   [x] Implement handler calling `taskManager.updateTaskStatus()`.
    *   [x] Add call to `historyLogger.log()`.
    *   [x] Implement error handling (`try/catch`) and return appropriate MCP response.
*   [x] **Define & Implement `suggest_next_task` Tool:**
    *   [x] Define with `server.tool()`, including `zod` schema for `feature_identifier`.
    *   [x] Implement handler calling `taskManager.suggestNextTask()`.
    *   [x] Implement error handling (`try/catch`) and return appropriate MCP response.
*   [x] **Define & Implement Context Retrieval Tools:**
    *   [x] `get_codebase_summary`: Define tool, implement handler using `fs.readFile`. Add error handling.
    *   [x] `get_history_log`: Define tool, implement handler using `fs.readFile`. Add error handling.
    *   [x] `get_feature_tasks`: Define tool (with `feature_identifier` arg), implement handler using `fs.readFile`. Add error handling for file not found.

## Phase 4: Cursor Integration & Finalization

*   [ ] **Create `.cursor/mcp.json`:**
    *   [ ] Define the connection URL for the Lamplighter-MCP server.
    *   [ ] List all implemented MCP tools accurately.
*   [ ] **Create `.cursor/rules/*.mdc` Files:**
    *   [ ] Write `system_overview.mdc` explaining Lamplighter-MCP's purpose and the role of each context file.
    *   [ ] Write `tool_reference.mdc` detailing each MCP tool (name, args, purpose).
    *   [ ] Write `workflow_guide.mdc` outlining key workflows, especially the "AI Suggestion + User Confirmation" flow for task completion.
*   [ ] **Refine Error Handling:** Review all `try/catch` blocks, ensure meaningful internal logs and user-facing MCP error responses.
*   [ ] **Testing:**
    *   [ ] Set up `jest` or another testing framework.
    *   [ ] Write basic unit tests for core utility functions (e.g., Markdown parsing, ID derivation).
    *   [ ] Write unit tests for core modules, mocking dependencies (`fs`, `axios`, `AIService`).
    *   [ ] *(Optional)* Write integration tests for MCP tool handlers (mocking core logic).
*   [ ] **Documentation:**
    *   [ ] Create/update project `README.md` with setup instructions, configuration details, and how to run the server.
    *   [ ] Ensure adequate code comments for complex sections.
    *   [ ] Finalize `.env.example`.

## Phase 5: Deployment & Testing

*   [x] **Build Production Version:** Ensure `npm run build` compiles TypeScript correctly.
*   [ ] **End-to-End Testing:**
    *   [x] Create comprehensive test plan (documents/e2e_testing_plan.md)
    *   [ ] Run the server locally (`npm start`).
    *   [ ] Configure Cursor with the local `.cursor/` directory.
    *   [ ] Manually test all MCP tools and workflows described in the PRD/ERD via Cursor prompts.
    *   [ ] Test error conditions (e.g., invalid Confluence URL, non-existent feature identifier).
    *   [ ] Verify context files (`.md`) are created/updated correctly.
    *   [ ] Verify `history_log.md` is appended correctly.
*   [x] **Deployment (if applicable):** Plan steps for deploying to a shared development server (documents/deployment_plan.md).