Content
# team-mode-mcp
**Turn any AI CLI into a coordinated engineering team**
---
## What is it
`team-mode-mcp` is a **MCP protocol-based team chat capability layer**.
- **18 MCP tools**: team / member / room / message / inbox / thread fully covered
- **Any AI tool supporting MCP can be integrated**: Codex, Claude Code, Cursor, OpenCode
- **Group chat as main interface**: users and leads see complete message flow; workers filter by visibility/mentions
- **No workflow binding**: system only provides message routing and state storage, skills determine agent behavior
- **Zero database**: all states exist in `.orchestry/` directory YAML/JSON files, out-of-the-box
---
## Quick Start
```bash
# Install dependencies
npm install
# Build
npm run build
# Run end-to-end test (verify all 18 tools are working)
node scripts/test_mcp_e2e.mjs
# Start MCP server (stdio transport)
node dist/cli.js mcp-server stdio
# Start with debug logging (output to stderr)
node dist/cli.js mcp-server stdio --verbose
```
---
## Tool Reference
All tools are called via `tools/call`, response format:
```json
{
"content": [{ "type": "text", "text": "<JSON payload>" }],
"structuredContent": "<payload>"
}
```
### Team Tools
| Tool | Description | Required Parameters |
|------|-------------|----------------------|
| `team_create` | Create team | `name`, `lead_agent_id` |
| `team_get` | Get team details | `team_id` |
| `team_list` | List all teams | — |
| `team_delete` | Dissolve team | `team_id` |
### Member Tools
| Tool | Description | Required Parameters |
|------|-------------|----------------------|
| `member_add` | Add member | `team_id`, `agent_id` |
| `member_remove` | Remove member | `team_id`, `agent_id` |
| `member_update` | Update member (support set to lead) | `team_id`, `agent_id` |
| `member_list` | List team members | `team_id` |
| `member_get` | Get single member info | `team_id`, `agent_id` |
### Room / Message Tools
| Tool | Description | Required Parameters |
|------|-------------|----------------------|
| `room_post_message` | Send message to main room | `sender`, `body` |
| `room_read_messages` | Read room message history | — |
| `room_list` | List rooms (v1 fixed main) | — |
### Inbox Tools
| Tool | Description | Required Parameters |
|------|-------------|----------------------|
| `inbox_peek` | View unread messages (no state change) | `agent_id` |
| `inbox_read` | Mark messages as read | `agent_id`, `message_ids` |
| `inbox_ack` | Confirm messages | `agent_id`, `message_ids` |
| `inbox_count` | Count inbox state | `agent_id` |
### Thread Tools
| Tool | Description | Required Parameters |
|------|-------------|----------------------|
| `thread_read` | Read thread messages | `agent_id`, `thread_id` |
| `thread_reply` | Reply in thread | `agent_id`, `thread_id`, `body` |
### JSON-RPC Error Codes
| Code | Meaning | Trigger Condition |
|------|---------|-------------------|
| -32600 | Invalid Request | jsonrpc != "2.0" or missing method |
| -32601 | Method/tool not found | unknown tool name |
| -32000 | Server error | parameter validation failed or runtime exception |
---
## Architecture
```
AI CLI (Codex / Claude Code / Cursor / OpenCode)
|
| stdio JSON-RPC (MCP Protocol, Content-Length framing)
|
MCP Server (src/cli/commands/mcp-server.ts)
— Content-Length frame parsing
— --verbose debug log → stderr
|
TeamModeMcpRuntime (src/infrastructure/mcp/team-mode-mcp-runtime.ts)
— 18 tool routes
— JSON-RPC error mapping
|
Application Services
— TeamService (src/application/team-service.ts)
— MessageService (src/application/message-service.ts)
|
ORCH Engine (domain + infrastructure)
— TeamStore / MessageStore / AgentStore
— atomicWrite (temp + rename, prevent file corruption)
|
.orchestry/ (YAML + JSONL + JSON files, no database)
agents/ — agent definition
teams/ — team state
messages/ — message history
```
**Stateless request dispatch**: each `handleRequest()` call is completed independently via `LightContainer` service layer, no in-memory session.
---
## Integration Guide
### Codex
Register in Codex's MCP configuration:
```json
{
"mcpServers": {
"team-mode": {
"command": "node",
"args": ["C:/orch-mcp/dist/cli.js", "mcp-server", "stdio"]
}
}
}
```
> **Windows Note**: if project path contains Chinese characters, create a junction to bypass encoding issues:
> ```cmd
> mklink /J C:\orch-mcp "E:\your\project\path"
> ```
### Claude Code
```json
{
"mcpServers": {
"team-mode": {
"command": "node",
"args": ["/path/to/dist/cli.js", "mcp-server", "stdio"]
}
}
}
```
### Debugging
```bash
# Redirect stderr log to file
node dist/cli.js mcp-server stdio --verbose 2>debug.log
```
---
## Development Guide
### Requirements
- Node.js >= 20
- TypeScript (included in devDependencies)
### Core Files
| File | Description |
|------|-------------|
| `src/infrastructure/mcp/team-mode-mcp-runtime.ts` | 18 MCP tool implementations, core |
| `src/cli/commands/mcp-server.ts` | stdio transport layer, Content-Length frame |
| `src/application/team-service.ts` | team CRUD business logic |
| `src/application/message-service.ts` | message send/route/inbox logic |
| `src/domain/team.ts` | Team / TeamMember type definition |
| `src/domain/message.ts` | Message / InboxItem type definition |
| `src/infrastructure/storage/` | YAML/JSON persistence, atomicWrite |
| `scripts/test_mcp_e2e.mjs` | end-to-end integration test, 10 steps cover full flow |
### Common Commands
```bash
npm run build # build ESM + DTS
npm test # run all unit tests (vitest)
npm run typecheck # TypeScript strict type check
npm run coverage # test coverage report
node scripts/test_mcp_e2e.mjs # MCP end-to-end integration test
```
### Add New MCP Tool
1. Add tool definition (name / description / inputSchema) to `listTools()` return array in `team-mode-mcp-runtime.ts`
2. Add corresponding case to `_callToolImpl()` switch
3. Add test step in `scripts/test_mcp_e2e.mjs`
4. Update tool table in `docs/api-contracts.md`
---
## Design Principles
### Group Chat as Main Interface
All collaboration is done through group chat message flow. users and leads see complete flow; workers filter by `visibility` / `mentions` field, only receiving messages related to themselves.
### @Assignment is the Only Formal Assignment Signal
Only messages containing at least one valid `@member` mention are formal assignments. messages without `@mention` are discussions/context and should not be treated as assignments.
### Skills Determine Behavior, Protocol is Not Bound
System only provides message routing and state storage. agent's specific behavior is injected into prompt by its `skills` field, decoupled from Team Mode protocol.
### No Dependence on Single CLI
MCP protocol layer has no requirements for CLI tools; any MCP client supporting `tools/call` can be integrated.
### Recoverability First
All states are written to files in `.orchestry/` directory. process restart can recover complete state from files, no need to rebuild in-memory state.
---
## License
MIT — see [LICENSE](./LICENSE)
