doit-mcp-server: Instructions file for Codex

AGENTS.md

Public Repo

This repo is public. Do not commit or write into PR titles/descriptions: internal Jira issue keys (e.g. CMP-1234), names of private/internal repos, or other internal-only details. Keep references generic (e.g. "a separate private repo") instead.

Environment Setup

Requires Node.js >=20 (the MCP SDK v2 packages set that floor). Install dependencies before running any commands:

yarn install

Yarn 4.18.1 via Corepack. Enable Corepack before using Yarn. The root project and test/integration are separate projects with their own modern yarn.lock files and packageManager pins. Both use the node-modules linker. CI installs with yarn install --immutable; migrate both projects and their workflows together.

Never run npm install. npm lockfiles are gitignored, rejected by the no-npm-lockfiles pre-commit hook, and fail the Enforce yarn step in test.yml. npm is still used deliberately for publishing only — release.yml's publish-npm job needs the npm CLI for Trusted Publishing (OIDC + provenance), which yarn cannot do. That is registry publication, not dependency management. There is deliberately no local publish script: publishing happens only from that CI job.

Project Overview

DoiT MCP Server is a Model Context Protocol (MCP) server that provides LLMs with access to the DoiT API.

This repo is the stdio MCP server plus a transport-independent core package:

1. stdio server (src/) - Core MCP server implementation using stdio transport

   • Published as @doitintl/doit-mcp-server on npm
   • Runs locally via npx or stdio connection
   • Entry point: src/index.ts

2. Core export (src/core.ts) - Transport-independent tools, prompts, and utilities

   • Published as the @doitintl/doit-mcp-server/core subpath
   • Consumed by a remote Cloudflare Worker that lives in a separate private repo

Project Structure

Main Package (src/)

src/
├── index.ts              # Entry point (stdio transport)
├── stdio.ts              # serveDoitStdio: serves 2025-era and 2026-07-28 clients (see docs/protocol-compatibility.md)
├── server.ts             # MCP server setup and request handlers (createServer is the per-connection factory)
├── tools/                # MCP tool implementations
│   └── __tests__/        # Tool tests
├── types/                # Tools and general type definitions
├── utils/                # Shared utilities
│   ├── util.ts           # General utilities (debugLog, etc.)
│   ├── prompts.ts        # MCP prompt definitions
│   ├── consts.ts         # Constants
│   ├── toolsHandler.ts   # Tool request handler
│   └── __tests__/        # Utility tests
└── __tests__/            # Server-level tests