Lucas Winther
e70e329e9d
- Add AGENTS.md defining coding standards, security, and workflows - Add GEMINI.md and CLAUDE.md referencing AGENTS.md - Add docs/ARCHITECTURE.md detailing MCP server design and OpenProject API integration - Add docs/DECISIONS.md with initial ADRs (stack, transport, auth, scoping) - Add .gitignore for Node.js and secrets protection
80 lines
4.8 KiB
Markdown
80 lines
4.8 KiB
Markdown
# Agent Guidelines for openproject-mcp
|
|
|
|
Welcome to the `openproject-mcp` project. This document defines operating principles, architectural conventions, coding practices, and workflow expectations for AI agents collaborating on this codebase.
|
|
|
|
## 1. Project Overview
|
|
|
|
`openproject-mcp` is a Model Context Protocol (MCP) server that acts as an intelligent bridge to [OpenProject](https://github.com/opf/openproject). It enables LLM agents and clients (e.g., Claude Desktop, Antigravity, Cursor) to browse, query, and interact with OpenProject instances using user API keys via OpenProject's REST API v3.
|
|
|
|
### Primary Objectives
|
|
- Expose OpenProject projects, work packages, queries, users, and taxonomies as MCP tools and resources.
|
|
- Provide secure, transparent authentication via OpenProject API tokens.
|
|
- Handle OpenProject's HAL+JSON schema and complex query filter syntax gracefully.
|
|
- Ensure lightweight, resilient runtime execution over standard MCP transports (stdio).
|
|
|
|
---
|
|
|
|
## 2. General Principles for Agents
|
|
|
|
1. **Check Documentation First**: Before proposing or executing architectural changes, consult [docs/ARCHITECTURE.md](file:///home/user/openproject-mcp/docs/ARCHITECTURE.md) and [docs/DECISIONS.md](file:///home/user/openproject-mcp/docs/DECISIONS.md).
|
|
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.
|
|
|
|
---
|
|
|
|
## 3. Technology Stack & Coding Standards
|
|
|
|
### Stack
|
|
- **Language**: TypeScript (targeting ES2022 / Node.js >= 18).
|
|
- **MCP Framework**: Official `@modelcontextprotocol/sdk`.
|
|
- **Validation**: `zod` for input schema validation and TypeScript inference.
|
|
- **HTTP Client**: Native `fetch` or a minimal strongly-typed wrapper (e.g., `undici` or `axios` if required for streaming/interceptors).
|
|
- **Testing**: Vitest or Jest with fixture-based mocking for HAL+JSON API responses.
|
|
|
|
### Code Style
|
|
- **TypeScript**: Strict type checking enabled (`strict: true` in `tsconfig.json`). Avoid `any` - use `unknown` with type guards or explicit Zod schemas.
|
|
- **Modularity**: Separate transport/MCP protocol concerns from OpenProject domain logic and HTTP client handling.
|
|
- **Naming Conventions**:
|
|
- Files and directories: `kebab-case` (e.g., `openproject-client.ts`, `work-packages.ts`).
|
|
- Types and Interfaces: `PascalCase` (e.g., `OpenProjectConfig`, `WorkPackageResource`).
|
|
- Functions and variables: `camelCase` (e.g., `fetchWorkPackage`, `projectIdentifier`).
|
|
- Constants: `UPPER_SNAKE_CASE` (e.g., `DEFAULT_PAGE_SIZE`, `API_V3_PREFIX`).
|
|
- MCP Tool Names: `snake_case` prefixed with domain (e.g., `openproject_list_projects`, `openproject_get_work_package`).
|
|
|
|
---
|
|
|
|
## 4. OpenProject API Integration Guidelines
|
|
|
|
### Authentication
|
|
- OpenProject REST API v3 uses HTTP Basic Authentication for API keys:
|
|
- Username: `apikey`
|
|
- Password: `<USER_API_KEY>`
|
|
- Header format: `Authorization: Basic base64(apikey:<USER_API_KEY>)`
|
|
- Base URL format: `<protocol>://<host>[:port]` (e.g., `https://openproject.example.com`). The API v3 root is at `/api/v3`.
|
|
|
|
### HAL+JSON Format
|
|
- OpenProject responses use HAL+JSON format (`_links`, `_embedded`).
|
|
- Agents must ensure parsing utilities extract canonical identifiers and friendly representations for LLM consumption rather than dumping raw deep HAL trees when not needed.
|
|
|
|
### Filters and Pagination
|
|
- OpenProject API v3 filters use JSON string parameters (e.g., `filters=[{"status_id":{"operator":"o","values":[]}}]`).
|
|
- Tool handlers should accept clean, human/LLM-friendly arguments (e.g., `status: "open"`, `projectId: 12`) and translate them into OpenProject's filter syntax.
|
|
|
|
---
|
|
|
|
## 5. Security & Safety
|
|
|
|
- **Secrets Management**: Read `OPENPROJECT_BASE_URL` and `OPENPROJECT_API_KEY` from environment variables. Never hardcode credentials in tests, scripts, or examples.
|
|
- **Input Validation**: All tool parameters must be validated via Zod schemas before being used in HTTP requests.
|
|
- **Safe Error Propagation**: Sanitize error messages returned to the MCP client. Never leak authorization headers or system paths in tool error responses.
|
|
|
|
---
|
|
|
|
## 6. Development Workflow for Agents
|
|
|
|
1. **Understand Task Scope**: Read requirements and check existing code and docs.
|
|
2. **Test-Driven or Verification-Driven**: When writing or updating tools, verify against mock OpenProject API responses.
|
|
3. **Update Docs**: Keep `docs/ARCHITECTURE.md` and `docs/DECISIONS.md` synchronized with the actual codebase.
|
|
4. **Clean Commits**: Make focused, atomic commits with descriptive messages following Conventional Commits (e.g., `feat:`, `fix:`, `docs:`, `refactor:`).
|