# MACP

> Shared SQLite coordination layer and reference TypeScript CLI / MCP server for agents working on the same project.

MACP is the protocol. `macp-mcp` is the npm package and reference TypeScript CLI / MCP server.

## Discovery
- Agent docs: https://macp.dev/for-agents
- Machine-readable manifest: https://macp.dev/.well-known/mcp.json
- llms.txt: https://macp.dev/llms.txt
- GitHub repo: https://github.com/multiagentcognition/macp
- Tutorial: https://github.com/multiagentcognition/macp/blob/main/docs/TUTORIAL.md
- Extensions: https://github.com/multiagentcognition/macp/blob/main/docs/EXTENSIONS.md
- Schema: https://github.com/multiagentcognition/macp/blob/main/macp.schema.json
- Spec: https://github.com/multiagentcognition/macp/blob/main/spec/MACP-Protocol-v1.0.md

## Package
- npm package: `macp-mcp`
- package version: `2.1.0`
- protocol version: `MACP v1.0`
- runtime: Node.js 22.5+, SQLite 3.35+

## Install in the current project
Run in the project root:
```bash
npx -y macp-mcp init
```

This command:
- .macp/config.json
- a shared SQLite bus under .macp/
- .mcp.json for Claude Code
- opencode.json for OpenCode
- .gemini/settings.json for Gemini CLI
- .vscode/mcp.json and .cursor/mcp.json for editor MCP flows
- managed MACP blocks in AGENTS.md and CLAUDE.md

## Local clone path
```bash
npm install
npm run build
node build/src/cli.js init
```

## Manual server launch
```bash
npx -y macp-mcp server  --db /tmp/macp_demo.db  --project-id case-001  --agent-id agent-alpha  --agent-name Alpha  --role investigator  --interest-tags '["auth","credentials"]'
```

## Supported hosts
- Claude Code: .mcp.json, CLAUDE.md. Project-local auto-attach.
- OpenCode: opencode.json, AGENTS.md. Project-local auto-attach.
- Gemini CLI: .gemini/settings.json, AGENTS.md. Project-local auto-attach.
- Cursor / VS Code: .vscode/mcp.json, .cursor/mcp.json. Project-local MCP config is written for supported editor flows.
- Codex: AGENTS.md. Reads project instructions, but MCP attachment still needs Codex-side configuration.

## Core MCP tools
- `macp_get_instructions`
- `macp_register`
- `macp_join_channel`
- `macp_send_channel`
- `macp_send_direct`
- `macp_poll`
- `macp_ack`
- `macp_deregister`

## Workspace extensions
### Awareness
Active agent list and current session context.
- `macp_ext_list_agents`
- `macp_ext_get_session_context`

### File Ownership
Advisory file claims and lock listing.
- `macp_ext_claim_files`
- `macp_ext_release_files`
- `macp_ext_list_locks`

### Memory
Agent, channel, and workspace memory.
- `macp_ext_set_memory`
- `macp_ext_get_memory`
- `macp_ext_search_memory`
- `macp_ext_list_memories`
- `macp_ext_delete_memory`
- `macp_ext_resolve_memory`

### Profiles
Reusable roles, skills, and vault path hints.
- `macp_ext_register_profile`
- `macp_ext_get_profile`
- `macp_ext_list_profiles`
- `macp_ext_find_profiles`

### Goals
Hierarchical planning objects above the bus.
- `macp_ext_create_goal`
- `macp_ext_list_goals`
- `macp_ext_get_goal`
- `macp_ext_update_goal`
- `macp_ext_get_goal_cascade`

### Tasks
Shared work queue and task state transitions.
- `macp_ext_dispatch_task`
- `macp_ext_claim_task`
- `macp_ext_start_task`
- `macp_ext_complete_task`
- `macp_ext_block_task`
- `macp_ext_cancel_task`
- `macp_ext_get_task`
- `macp_ext_list_tasks`
- `macp_ext_archive_tasks`

### Lifecycle
Sleep, deactivate, and delete agent sessions.
- `macp_ext_sleep_agent`
- `macp_ext_deactivate_agent`
- `macp_ext_delete_agent`

### Vault / Docs
Index and search workspace docs from the shared SQLite file.
- `macp_ext_register_vault`
- `macp_ext_search_vault`
- `macp_ext_get_vault_doc`
- `macp_ext_list_vault_docs`

### Context Search
Search visible memories, docs, goals, and completed tasks.
- `macp_ext_query_context`

## Normal autonomous flow
1. Open macp.dev and prefer /for-agents, /llms.txt, or /.well-known/mcp.json if available.
2. Run `npx -y macp-mcp init` in the project root.
3. Open a supported host in that same folder.
4. Let the host start `macp-mcp` and auto-register the session on startup.
5. Use `macp_poll`, `macp_send_channel`, `macp_send_direct`, and `macp_ack` inside the normal work loop.

## Direct docs
- Instructions template: https://github.com/multiagentcognition/macp/blob/main/examples/MACP_COORDINATION.md
- Security notes: https://github.com/multiagentcognition/macp/blob/main/docs/SECURITY.md