From 4251c03e426a6d73240a48a9cac868e30236c3ac Mon Sep 17 00:00:00 2001
From: Lucas Winther <lucwin@ece.au.dk>
Date: Sat, 5 Sep 2026 16:36:00 +0200
Subject: [PATCH] docs: adapt project guidelines, architecture, and ADRs for
 Bun

- Update AGENTS.md, CLAUDE.md, and GEMINI.md with Bun workflow rules and bun:test

- Update docs/ARCHITECTURE.md with Bun runtime layer and lockfile

- Add ADR-010 in docs/DECISIONS.md superseding ADR-001 with Bun adoption

- Update README.md with Bun prerequisites, installation, and run instructions
---
 AGENTS.md            | 15 ++++++++++++---
 CLAUDE.md            | 32 ++++++++++++++++++++++++++++++--
 GEMINI.md            |  5 ++++-
 README.md            | 30 +++++++++++++++++++++++++++++-
 docs/ARCHITECTURE.md |  4 +++-
 docs/DECISIONS.md    | 32 +++++++++++++++++++++++++++++++-
 6 files changed, 109 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 283e364..9b77094 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -26,11 +26,20 @@ Welcome to the `openproject-mcp` project. This document defines operating princi
 ## 3. Technology Stack & Coding Standards
 
 ### Stack
-- **Language**: TypeScript (targeting ES2022 / Node.js >= 18).
+- **Runtime & Package Manager**: **Bun** (>= 1.2 / 1.3).
+  - Default to using Bun instead of Node.js.
+  - Use `bun <file>` instead of `node <file>` or `ts-node <file>`.
+  - Use `bun test` instead of `jest` or `vitest` (using `import { test, expect, describe } from "bun:test"`).
+  - Use `bun add` / `bun install` instead of `npm install`, `pnpm`, or `yarn`.
+  - Use `bun run <script>` instead of `npm run <script>`.
+  - Use `bunx <package>` instead of `npx <package>`.
+  - Bun automatically loads `.env` and `.env.local`, so do not introduce external packages like `dotenv`.
+  - Prefer `Bun.file` over `node:fs` for reading and writing files.
+- **Language**: TypeScript (running natively on Bun with ESNext target, `bundler` module resolution, strict mode).
 - **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.
+- **HTTP Client**: Native `fetch` (high-performance built-in implementation in Bun).
+- **Testing**: `bun:test` 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.
diff --git a/CLAUDE.md b/CLAUDE.md
index c7e183c..f68a989 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,33 @@
 # Claude Instructions for openproject-mcp
 
-Please refer to [AGENTS.md](./AGENTS.md) for all project guidelines, coding conventions, architectural standards, and workflow instructions.
+Please refer to [AGENTS.md](./AGENTS.md) for primary project guidelines, coding conventions, architectural standards, and workflow instructions.
 
-All agents and assistants operating in this repository must follow the instructions defined in `AGENTS.md`.
+---
+
+## Runtime & Tooling (Bun)
+
+Default to using Bun instead of Node.js:
+
+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
+- Use `bun test` instead of `jest` or `vitest`
+- Use `bun install` / `bun add` instead of `npm install` or `pnpm install`
+- Use `bun run <script>` instead of `npm run <script>`
+- Use `bunx <package> <command>` instead of `npx <package> <command>`
+- Bun automatically loads `.env` and `.env.local`, so don't use `dotenv`.
+- Prefer `Bun.file` over `node:fs` for reading and writing files.
+
+## Testing
+
+Use `bun test` to run tests:
+
+```ts
+import { test, expect, describe } from "bun:test";
+
+describe("OpenProject Client", () => {
+  test("authenticates via Basic Auth", () => {
+    expect(1).toBe(1);
+  });
+});
+```
+
+For full details on project architecture and decisions, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/DECISIONS.md](docs/DECISIONS.md).
diff --git a/GEMINI.md b/GEMINI.md
index d490463..34b642c 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -2,4 +2,7 @@
 
 Please refer to [AGENTS.md](./AGENTS.md) for all project guidelines, coding conventions, architectural standards, and workflow instructions.
 
-All agents and assistants operating in this repository must follow the instructions defined in `AGENTS.md`.
+All agents operating in this repository must default to **Bun** instead of Node.js:
+- Run commands with `bun run <script>`, `bun <file>`, and `bun test`.
+- Manage dependencies with `bun add` and `bun install`.
+- Rely on Bun's built-in TypeScript execution and `.env` loading.
diff --git a/README.md b/README.md
index 462835e..01e2d30 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ A complete OpenProject 17 environment with PostgreSQL 17 and Memcached is includ
 ### Prerequisites
 
 - Docker and Docker Compose (v2+)
-- Node.js (>= 18) and npm
+- [Bun](https://bun.sh) (>= 1.2 / 1.3)
 
 ### 1. Start the Environment & Seed Data
 
@@ -89,6 +89,34 @@ docker compose down -v
 
 ---
 
+## MCP Server Development (Bun)
+
+Install project dependencies:
+
+```bash
+bun install
+```
+
+Start the MCP server over stdio:
+
+```bash
+bun run src/index.ts
+```
+
+Run test suite:
+
+```bash
+bun test
+```
+
+Type-check:
+
+```bash
+bun run typecheck
+```
+
+---
+
 ## Configuration
 
 The MCP server accepts configuration through environment variables or a `.env` file:
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index d63634d..83b46c3 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -47,6 +47,7 @@ flowchart LR
 The system is organized into four modular layers:
 
 ### 2.1. MCP Server & Transport Layer
+- **Runtime**: **Bun** (>= 1.2/1.3) providing native TypeScript execution without build steps, automatic `.env` loading, and fast startup for CLI/stdio subprocesses.
 - **Responsibility**: Manages the MCP connection lifecycle, tool definitions, input validation, and JSON-RPC dispatching.
 - **Protocol**: MCP specification implemented via `@modelcontextprotocol/sdk`.
 - **Default Transport**: `StdioServerTransport` for local integration with desktop clients and CLI tools.
@@ -159,7 +160,8 @@ openproject-mcp/
 │   └── tools.test.ts            # MCP tool integration tests
 ├── AGENTS.md                    # Operating guidelines for AI agents
 ├── package.json                 # Project dependencies and scripts
-└── tsconfig.json                # TypeScript compiler configuration
+├── bun.lock                     # Bun dependency lockfile
+└── tsconfig.json                # TypeScript compiler configuration (Bun bundler mode)
 ```
 
 ---
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 557d100..c3a031c 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -7,7 +7,7 @@ This document records the key architectural and technical decisions made for `op
 ## ADR-001: Technology Stack Selection (TypeScript & Node.js)
 
 ### Status
-Accepted
+Superseded by ADR-010
 
 ### Context
 We need to build a companion MCP server for OpenProject (https://github.com/opf/openproject) that runs reliably on local machines and integrates smoothly with MCP clients such as Claude Desktop, Cursor, and Antigravity.
@@ -205,3 +205,33 @@ Target **OpenProject 17** (`openproject/openproject:17-slim`) for all containeri
 - **Negative**:
   - Ensures we adhere to OpenProject 17's specific cache configuration and host name variables.
 
+---
+
+## ADR-010: Adopt Bun as Runtime, Package Manager, and Test Runner
+
+### Status
+Accepted (Supersedes ADR-001)
+
+### Context
+MCP servers are typically spawned by LLM desktop clients (Claude Desktop, Cursor, Antigravity) as child processes over `stdio`. Fast startup time, low memory footprint, zero compilation lag for TypeScript files, and integrated test runner ergonomics are vital for agentic development workflows.
+
+Bun provides:
+1. Native TypeScript and JSX execution without intermediate build steps or transpilers (`ts-node`, `esbuild`, `tsc`).
+2. Extremely fast package management (`bun install` in sub-second speeds) with modern text-based `bun.lock`.
+3. Built-in test runner (`bun test`, `bun:test`) eliminating external dependencies like Jest or Vitest.
+4. Native environment variable loading (`.env`, `.env.local`) without needing `dotenv`.
+5. High-performance native `fetch` and `Bun.file` APIs.
+
+### Decision
+Adopt **Bun** (>= 1.2 / 1.3) as the exclusive runtime, package manager, and test runner for `openproject-mcp`.
+
+### Consequences
+- **Positive**:
+  - Immediate startup with zero transpile overhead: `bun run src/index.ts`.
+  - Ultra-fast test execution: `bun test`.
+  - Simpler dependency tree: no `dotenv`, `ts-node`, `vitest`, or `jest`.
+  - Seamless developer experience matching Bun's project initialization conventions.
+- **Negative**:
+  - Requires the host machine to have Bun installed rather than traditional Node.js/npm.
+
+