# codex-omnifocus-mcp

Local Codex-focused MCP server for OmniFocus on macOS.

This project starts from `omnifocus-mcp-enhanced` and adds Codex-oriented server instructions, MCP resources, compact query tools, tag tools, clean shutdown, logging, and write audit logging.

## What This Repo Is

This repository is the source code for a local MCP server. It is not a hosted web service and it does not run a central cloud server.

Each user installs this repo on their own Mac. Codex starts the MCP server locally with Node.js, talks to it over stdio, and the server reads or updates the user's local OmniFocus database through AppleScript/JXA.

In short:

```text
Codex -> local MCP stdio -> node dist/server.js -> AppleScript/JXA -> OmniFocus
```

The GitHub repo's role is distribution: source code, docs, install scripts, tests, and release history.

## Install From A Clone

```bash
git clone https://github.com/phd-peter/codex-omnifocus-mcp.git ~/.local/share/codex-omnifocus-mcp
cd ~/.local/share/codex-omnifocus-mcp
scripts/install-codex.sh
```

To clone from a script-driven install after downloading this script separately:

```bash
CODEX_OMNIFOCUS_REPO_URL=https://github.com/phd-peter/codex-omnifocus-mcp.git scripts/install-codex.sh
```

The installer runs `npm ci`, builds the TypeScript output, and registers the MCP server with Codex:

```bash
codex mcp add codex-omnifocus -- node /path/to/codex-omnifocus-mcp/dist/server.js
```

If Codex does not show the new tools immediately, restart Codex or open a new Codex session.

## Local Development

```bash
npm install
npm run build
codex mcp add codex-omnifocus -- node "$PWD/dist/server.js"
```

The server is intended for local use. `package.json` remains marked `private` as an npm publishing guard; the GitHub repository can still be public.

Useful commands:

```bash
npm test
npm run build
npm run preflight
npm run register:codex
```

## Create Your Own OmniFocus Agent

This repo provides the shared MCP server and the default Codex tool-use guidance in `skills/codex-omnifocus/SKILL.md`. Your personal agent behavior should live in a separate `AGENTS.md` so each user can define their own OmniFocus system without changing the server.

Start from the template:

```bash
cp AGENTS.example.md AGENTS.md
```

Then edit `AGENTS.md` for your own workflow:

- default capture destination
- tags and custom perspectives
- due/defer date habits
- daily planning and weekly review style
- when the agent may write directly and when it should ask first

Personal `AGENTS.md` files are ignored by default because they can include sensitive project names, routines, or decision rules.

## Audit Logs

Write tools append JSONL entries to:

```text
~/.codex/codex-omnifocus-mcp/audit/YYYY-MM-DD.jsonl
```

Override the directory with:

```bash
export CODEX_OMNIFOCUS_AUDIT_DIR=/path/to/audit
```

Audited tools:

- `add_omnifocus_task`
- `add_project`
- `edit_item`
- `move_task`
- `remove_item`
- `batch_add_items`
- `batch_remove_items`
- `create_tag`

## Verification

```bash
npm test
npm run build
npm audit --omit=dev
```

OmniFocus integration tests should be run manually with OmniFocus open on macOS.

## Privacy

See `PRIVACY.md`. Audit logs and OmniFocus exports can contain private task, project, tag, date, and note data. Do not commit `backups/`, `exports/`, `.env*`, `audit/`, or `*.jsonl`.

## Architecture

See `docs/architecture.md` for the local runtime model and trust boundary.

## Distribution

See `docs/distribution.md` for the public GitHub, local-first release strategy.

## Marketing

See `docs/marketing.md` for launch positioning, channels, content ideas, and the first 30 days of public distribution work.

## Notices

See `NOTICE.md` for upstream attribution.