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

12 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).

  • Task 7: Hosted Remote MCP Server (HTTP/SSE Transport) & Multi-Tenant Credential Scoping

    • Extend configuration loader with port and host options (src/config/index.ts, tests/config.test.ts).
    • Implement hosted HTTP/SSE MCP server with Bun.serve and Web Streams SSE (src/http-server.ts, tests/http-server.test.ts).
    • Implement credential extraction hierarchy (Authorization: Bearer, X-OpenProject-Api-Key, ?apiKey=) with 401 unauthorized rejection.
    • Implement per-session client isolation and runWithContext dynamic scoping.
    • Wire dual-transport execution in CLI entrypoint (src/index.ts).
    • Create production docker-compose.server.yml with /health check probe.
    • Record ADR-016.
    • Update documentation with hosted deployment guide and remote client setups for Cursor and Claude Desktop in README.md.

  • Task 8: OpenAPI 3.1.0 Specification & REST Tool Execution Bridge

    • Implement dynamic OpenAPI specification generator src/openapi-spec.ts.
    • Expose GET /openapi.json and GET /swagger.json in src/http-server.ts.
    • Expose REST tool execution endpoint POST /api/tools/:toolName with Zod parameter validation and RequestContext execution.
    • Add automated test coverage in tests/http-server.test.ts.
    • Record ADR-017 in docs/DECISIONS.md.
    • Document OpenAPI connection mode and server endpoints reference table in README.md.

  • Task 9: Meetings, Wikis, and Activities Extension (18 Tools Total)

    • Implemented listWorkPackageActivities in src/services/work-packages.ts separating comments from field mutations with onlyComments filter.
    • Implemented listMeetings, getMeeting (with embedded agenda items/outcomes), and searchMeetings (deep search across titles, locations, and agenda item notes) in src/services/meetings.ts.
    • Implemented getWikiPage (with attachments), listWikiPageLinks, and searchWikiPages with smart discovery caching and consecutive 404 cutoff in src/services/wikis.ts.
    • Registered openproject_list_work_package_activities in src/tools/work-packages.ts.
    • Registered openproject_list_meetings, openproject_get_meeting, openproject_search_meetings in src/tools/meetings.ts.
    • Registered openproject_get_wiki_page, openproject_search_wiki_pages, openproject_list_wiki_page_links in src/tools/wikis.ts.
    • Wired all 18 tools into server registry (src/tools/index.ts, src/services/index.ts) and updated all test suite assertions to 18 tools.
    • Added live OpenProject 17 container integration tests in tests/services.test.ts and tests/mcp-server.test.ts.
    • Recorded ADR-018 and updated ARCHITECTURE.md, TODO.md, and README.md.

3. Backlog & Future Phases

  • Phase 4: Remote Transport (Completed)
    • Add SSE (Server-Sent Events) transport option for remote deployments.
    • Multi-tenant credential scoping with per-session isolation.
  • Phase 3 Extension: Meetings, Wikis, and Activities (Completed - 18 Tools Total)
    • Meetings listing, detail inspection, and deep agenda search.
    • Wiki pages retrieval, smart cached discovery search, and work package links.
    • Work package activities and comments filtering.
  • 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 (Future): Binary Attachments & File Resources
    • Inspect and download binary attachment file contents via MCP resources.
Reference in New Issue View Git Blame Copy Permalink