diff --git a/AGENTS.md b/AGENTS.md index 9b77094..397f6a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,8 @@ Welcome to the `openproject-mcp` project. This document defines operating princi 2. **Document Architectural Decisions**: If a change alters the design, dependencies, or interfaces, record a new entry or update existing records in [docs/DECISIONS.md](file:///home/user/openproject-mcp/docs/DECISIONS.md). 3. **Preserve Repository Integrity**: Do not delete existing comments, licenses, or configuration files unless specifically tasked with refactoring them. 4. **Security by Design**: Never log or commit credentials, API tokens, or session secrets. +5. **Never Continue Automatically**: Never proceed automatically to the next task or phase. Always stop and check in with the user after completing a task, outline the next logical step, and await explicit approval. +6. **Maintain Task Tracking**: Keep [docs/TODO.md](file:///home/user/openproject-mcp/docs/TODO.md) updated with completed items and next steps after every milestone. --- diff --git a/README.md b/README.md index 01e2d30..d2a80e3 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ It allows agents to browse, query, and reason about OpenProject workspaces using - [AGENTS.md](AGENTS.md): Guidelines, coding standards, and workflow instructions for AI coding agents. - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): System architecture, layer diagrams, tool schemas, and technical design. - [docs/DECISIONS.md](docs/DECISIONS.md): Architectural Decision Records (ADRs) documenting stack choices, protocols, and designs. +- [docs/TODO.md](docs/TODO.md): Task tracking, roadmap, and agent check-in policies. --- diff --git a/docs/TODO.md b/docs/TODO.md new file mode 100644 index 0000000..20154aa --- /dev/null +++ b/docs/TODO.md @@ -0,0 +1,92 @@ +# Project Progress & Roadmap + +> [!IMPORTANT] +> **CRITICAL AGENT POLICY**: +> **Never continue automatically to the next task or phase.** +> After finishing any individual task, milestone, or commit, the agent must **always stop and check in with the user**. Present what was completed, outline the next logical step, and await explicit user approval before proceeding. + +--- + +## 1. Completed Tasks + +- [x] **Agentic Development Guidelines & Infrastructure** + - [x] Created [AGENTS.md](../AGENTS.md) defining architectural conventions, coding practices, and agent workflow. + - [x] Created [CLAUDE.md](../CLAUDE.md) and [GEMINI.md](../GEMINI.md) pointing to [AGENTS.md](../AGENTS.md). + - [x] Created [docs/ARCHITECTURE.md](ARCHITECTURE.md) documenting layers, data flow, tool specifications, and API specifics. + - [x] Created [docs/DECISIONS.md](DECISIONS.md) establishing initial ADRs (stack, transport, auth, scoping, testing). + - [x] Created root [.gitignore](../.gitignore) protecting credentials, cache, and IDE artifacts. + +- [x] **OpenProject 17 Local Docker Stack & Seeding** + - [x] Created [docker-compose.yml](../docker-compose.yml) configured for OpenProject 17 (`openproject/openproject:17-slim`), PostgreSQL 17, and Memcached. + - [x] Created [.env.example](../.env.example) documenting all stack and MCP client environment variables. + - [x] Created [scripts/seed-test-data.rb](../scripts/seed-test-data.rb) (Rails runner script) to: + - Activate default admin user and remove password reset requirements. + - Generate a live personal API token via `Token::API.create_and_return_value(admin)`. + - Seed dedicated test project `mcp-test-project` (ID: 4). + - Seed 4 custom work packages (IDs: 38-41) across Task, Bug, Feature types. + - Seed saved query `MCP Active Tasks` (ID: 30). + - [x] Created [scripts/seed.sh](../scripts/seed.sh) orchestrating health checks and automated writing to `.env.test` and `.env.local`. + - [x] Created lifecycle scripts [scripts/start.sh](../scripts/start.sh) and [scripts/stop.sh](../scripts/stop.sh). + - [x] Verified live container execution and validated HTTP 200 API v3 access (`/api/v3/projects`) with generated token. + - [x] Recorded [ADR-009](DECISIONS.md#adr-009-target-openproject-17-as-primary-runtime-and-test-environment) targeting OpenProject 17. + +- [x] **Bun Runtime Migration & Tooling** + - [x] Switched project runtime from Node.js to Bun (v1.3.14). + - [x] Created [package.json](../package.json) with `@modelcontextprotocol/sdk` and `zod`. + - [x] Created [tsconfig.json](../tsconfig.json) with Bun bundler settings and strict typing. + - [x] Generated [bun.lock](../bun.lock). + - [x] Added [src/index.ts](../src/index.ts) entrypoint stub and [tests/smoke.test.ts](../tests/smoke.test.ts) using `bun:test`. + - [x] Updated [AGENTS.md](../AGENTS.md), [CLAUDE.md](../CLAUDE.md), and [GEMINI.md](../GEMINI.md) with Bun init rules. + - [x] Recorded [ADR-010](DECISIONS.md#adr-010-adopt-bun-as-runtime-package-manager-and-test-runner) adopting Bun. + - [x] Updated [README.md](../README.md) with Bun prerequisites and quickstart commands. + +--- + +## 2. Next Up (Phase 1: Read/Browse Implementation) + +- [ ] **Task 1: OpenProject REST API v3 Client Layer** + - [ ] Implement `src/config/index.ts` to parse and validate `OPENPROJECT_BASE_URL` and `OPENPROJECT_API_KEY` via Zod. + - [ ] Implement `src/client/api-client.ts` with native `fetch`, HTTP Basic Auth injection, error normalization, and rate/timeout handling. + - [ ] Implement `src/client/hal-parser.ts` to unpack HAL+JSON (`_links`, `_embedded`) into clean, token-efficient JSON models. + - [ ] Implement `src/client/filter-builder.ts` to translate LLM-friendly filter arguments into OpenProject's JSON filter syntax. + - [ ] Add unit tests in `tests/client.test.ts` verifying authentication headers, response parsing, and error sanitization against live container. + +- [ ] **Task 2: Domain Services** + - [ ] Implement `src/services/projects.ts` (`listProjects`, `getProject`). + - [ ] Implement `src/services/work-packages.ts` (`listWorkPackages`, `getWorkPackage`, `searchWorkPackages`). + - [ ] Implement `src/services/queries.ts` (`listQueries`, `getQuery`). + - [ ] Implement `src/services/metadata.ts` (`listStatuses`, `listTypes`, `listPriorities`, `listUsers`). + - [ ] Add service tests in `tests/services.test.ts`. + +- [ ] **Task 3: MCP Tool Definitions & Schema Registration** + - [ ] Define Zod schemas and register tools in `src/tools/`: + - `openproject_list_projects` + - `openproject_get_project` + - `openproject_list_work_packages` + - `openproject_get_work_package` + - `openproject_list_queries` + - `openproject_get_query` + - `openproject_list_types` + - `openproject_list_statuses` + - `openproject_list_priorities` + - `openproject_list_users` + +- [ ] **Task 4: MCP Stdio Server Assembly & Integration** + - [ ] Wire domain tools into `@modelcontextprotocol/sdk` Server using `StdioServerTransport` in `src/server.ts` and `src/index.ts`. + - [ ] Ensure all logging is strictly redirected to `stderr`. + - [ ] Add end-to-end integration tests in `tests/mcp-server.test.ts` verifying tool calling against the running OpenProject 17 instance. + +--- + +## 3. Backlog & Future Phases + +- [ ] **Phase 2: Mutating Operations** + - [ ] Create work package tool (`openproject_create_work_package`). + - [ ] Update work package tool (`openproject_update_work_package`). + - [ ] Add comments / activities to work packages. + - [ ] Time logging tool (`openproject_log_time`). +- [ ] **Phase 3: Attachments & Documents** + - [ ] Inspect and download attachment resources. + - [ ] Wiki pages and project documents browsing. +- [ ] **Phase 4: Remote Transport** + - [ ] Add SSE (Server-Sent Events) transport option for remote deployments.