lucasw89/openproject-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1f3eae4258802f227016a8acd6f8a9d3eb443bd9
openproject-mcp/docs/TODO.md
T

8.1 KiB
Raw Blame History

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

  • Agentic Development Guidelines & Infrastructure

    • Created AGENTS.md defining architectural conventions, coding practices, and agent workflow.
    • Created CLAUDE.md and GEMINI.md pointing to AGENTS.md.
    • Created docs/ARCHITECTURE.md documenting layers, data flow, tool specifications, and API specifics.
    • Created docs/DECISIONS.md establishing initial ADRs (stack, transport, auth, scoping, testing).
    • Created root .gitignore protecting credentials, cache, and IDE artifacts.

  • OpenProject 17 Local Docker Stack & Seeding

    • Created docker-compose.yml configured for OpenProject 17 (openproject/openproject:17-slim), PostgreSQL 17, and Memcached.
    • Created .env.example documenting all stack and MCP client environment variables.
    • Created 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).
    • Created scripts/seed.sh orchestrating health checks and automated writing to .env.test and .env.local.
    • Created lifecycle scripts scripts/start.sh and scripts/stop.sh.
    • Verified live container execution and validated HTTP 200 API v3 access (/api/v3/projects) with generated token.
    • Recorded ADR-009 targeting OpenProject 17.

  • Bun Runtime Migration & Tooling

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, OPENPROJECT_API_KEY, and OPENPROJECT_READ_ONLY (or --read-only) via Zod.
    • Implement src/context.ts providing RequestContext interface and AsyncLocalStorage scoping (getRequestContext, runWithContext) for concurrent multi-user safety.
    • 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/helper.ts (resolveClient for ambient RequestContext resolution).
    • Implement src/services/projects.ts (listProjects, getProject, getProjectSchema).
    • Implement src/services/work-packages.ts (listWorkPackages, getWorkPackage, searchWorkPackages).
    • Implement src/services/queries.ts (listQueries, getQuery, getQueryResults).
    • Implement src/services/metadata.ts (listStatuses, listTypes, listPriorities, listUsers).
    • Implement src/services/openapi.ts (getOpenApiSpec with in-memory caching, summary mode, path endpoint lookup, tag filtering, schema inspection).
    • Add service tests in tests/services.test.ts (unit tests and live container integration suite passing).

  • 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
      • openproject_get_openapi_spec

  • Task 4: MCP Stdio Server Assembly & Integration

    • Wire domain tools into @modelcontextprotocol/sdk Server using StdioServerTransport in src/server.ts and src/index.ts.
    • Implement read-only mode tool filtering (omits mutating tools when readOnly is enabled) and execution guard (SERVER_READ_ONLY).
    • 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.
    • Add read-only mode verification tests in tests/read-only.test.ts.

  • Task 5: OpenAPI Introspection Tool & Service

    • Implement src/services/openapi.ts with in-memory caching, multi-mode queries (summary, path, tag, schema), and ambient client resolution.
    • Implement src/tools/openapi.ts registering openproject_get_openapi_spec (readOnly: true) into allTools (bringing tool count to 11).
    • Add comprehensive test suite in tests/openapi.test.ts covering service methods, MCP client execution, error handling, and live OpenProject 17 container integration.
    • Update suite regressions and assertions across all test suites (tests/tools.test.ts, tests/read-only.test.ts, tests/mcp-server.test.ts).

  • Task 6: Docker Container Packaging & CI/CD Pipeline

    • Created multi-stage Dockerfile using oven/bun:1-slim builder and unprivileged bun user runner.
    • Created .dockerignore excluding secrets, local dependencies, test files, and docs from build context.
    • Implemented GitHub Actions CI workflow .github/workflows/ci.yml with automated type checking, testing, and multi-arch Docker image publishing (linux/amd64, linux/arm64) to ghcr.io.
    • Added automated test coverage in tests/docker.test.ts and tests/ci-workflow.test.ts.
    • Recorded ADR-015.
    • Updated README.md with Docker Quickstart, read-only mode instructions, and client integration settings (Claude Desktop & Cursor).

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.
Reference in New Issue View Git Blame Copy Permalink