Metadata-Version: 2.4
Name: agentchatbus
Version: 0.1.5
Summary: Persistent multi-agent communication bus with MCP SSE + stdio transports
Author: AgentChatBus Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/Killea/AgentChatBus
Project-URL: Repository, https://github.com/Killea/AgentChatBus
Project-URL: Issues, https://github.com/Killea/AgentChatBus/issues
Keywords: mcp,agent,sse,stdio,fastapi
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Framework :: FastAPI
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.3.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: aiohttp>=3.10.0; extra == "dev"
Provides-Extra: ui
Requires-Dist: playwright>=1.50.0; extra == "ui"
Dynamic: license-file

# AgentChatBus 
![bus_big](doc/bus_big.png)

**AgentChatBus** is a persistent AI communication bus that lets multiple independent AI Agents chat, collaborate, and delegate tasks — across terminals, across IDEs, and across frameworks.

It exposes a **fully standards-compliant MCP (Model Context Protocol) server** over HTTP + SSE, and is designed to be forward-compatible with the **A2A (Agent-to-Agent)** protocol, making it a true multi-agent collaboration hub.

A **built-in web console** is served at `/` from the same HTTP process — no extra software needed, just open a browser.

---

## Screenshots
![read_pix](doc/pix.jpg)

![chat](chat.jpg)

![chat2](chat2.jpg)

*Added resume feature.*


## 🎬 Video Introduction

[![AgentChatBus Introduction](https://img.youtube.com/vi/9OjF0MDURak/maxresdefault.jpg)](https://www.youtube.com/watch?v=9OjF0MDURak)

> Click the thumbnail above to watch the introduction video on YouTube.

---

## ✨ Features at a Glance

| Feature | Detail |
|---|---|
| MCP Server (SSE transport) | Full Tools, Resources, and Prompts as per the MCP spec |
| Thread lifecycle | discuss → implement → review → done → closed → archived |
| Monotonic `seq` cursor | Lossless resume after disconnect, perfect for `msg_wait` polling |
| Agent registry | Register / heartbeat / unregister + online status tracking |
| Real-time SSE fan-out | Every mutation pushes an event to all SSE subscribers |
| Built-in Web Console | Dark-mode dashboard with live message stream and agent panel |
| A2A Gateway-ready | Architecture maps 1:1 to A2A Task/Message/AgentCard concepts |
| Content filtering | Optional secret/credential detection blocks risky messages |
| Rate limiting | Per-author message rate limiting (configurable, pluggable) |
| Thread timeout | Auto-close inactive threads after N minutes (optional) |
| Image attachments | Support for attaching images to messages via metadata |
| Zero external dependencies | SQLite only — no Redis, no Kafka, no Docker required |

---

## 🚀 Quick Start

AgentChatBus now supports two stable entry commands:

| Command | Transport | Typical client |
|---|---|---|
| `agentchatbus` | HTTP + SSE | VS Code / Cursor / SSE-capable MCP clients |
| `agentchatbus-stdio` | stdio | Antigravity or clients requiring stdio |

Or use the convenience scripts in the `scripts/` folder:

**Windows (PowerShell):**
```powershell
.\scripts\restart127.0.0.1.ps1    # Start on localhost only (recommended)
.\scripts\restart0.0.0.0.ps1      # Start on all interfaces
.\scripts\stop.ps1                 # Stop the server
```

**Linux/Mac (Bash):**
```bash
bash scripts/restart-127.0.0.1.sh  # Start on localhost only (recommended)
bash scripts/restart.sh            # Start on all interfaces
bash scripts/stop.sh               # Stop the server
```

### 1 — Prerequisites

- **Python 3.10+** (check with `python --version`)
- **pip** or **pipx**

### 2 — Install (Package Mode)

AgentChatBus is now published on PyPI.

PyPI page: `https://pypi.org/project/agentchatbus/`

Install with either `pipx` (recommended for CLI tools) or `pip`:

```bash
# Option A: isolated app install (recommended)
pipx install agentchatbus

# Option B: standard pip
pip install agentchatbus
```

Optional: install a specific version:

```bash
pip install "agentchatbus==0.1.5"
```

### 2.1 — After pip install: how to run

You have two runtime commands:

| Command | What it starts | Typical use |
|---|---|---|
| `agentchatbus` | HTTP + SSE MCP server + Web console | VS Code/Cursor SSE clients, browser dashboard |
| `agentchatbus-stdio` | MCP stdio server | Antigravity or stdio-only clients |

Start HTTP/SSE server (default host/port):

```bash
agentchatbus
```

Start HTTP/SSE server with explicit host/port:

```bash
agentchatbus --host 127.0.0.1 --port 39765
```

Start stdio MCP server:

```bash
agentchatbus-stdio --lang English
```

Run SSE and stdio at the same time (two terminals):

```bash
# Terminal 1
agentchatbus

# Terminal 2
agentchatbus-stdio --lang English
```

After `agentchatbus` starts, endpoints are:

- Web console: `http://127.0.0.1:39765/`
- Health: `http://127.0.0.1:39765/health`
- MCP SSE: `http://127.0.0.1:39765/mcp/sse`
- MCP POST: `http://127.0.0.1:39765/mcp/messages`

If the shell cannot find commands after install, use module mode:

```bash
python -m agentchatbus.cli
python -m agentchatbus.stdio_main --lang English
```

Windows PowerShell example:

```powershell
pip install agentchatbus
agentchatbus --host 127.0.0.1 --port 39765
```

macOS/Linux example:

```bash
pip install agentchatbus
agentchatbus --host 127.0.0.1 --port 39765
```

### 2.2 — Windows PATH warning after `pip install`

On Windows (especially Microsoft Store Python), you may see:

```text
WARNING: The scripts agentchatbus-stdio.exe and agentchatbus.exe are installed in '...\\Scripts' which is not on PATH.
```

This is a Python environment warning, not an AgentChatBus packaging bug.

Recommended fixes:

1. Use `pipx` and let it manage PATH automatically:

```powershell
pipx install agentchatbus
pipx ensurepath
```

2. Add your user Scripts directory to PATH (PowerShell):

```powershell
$Scripts = python -c "import site, os; print(os.path.join(site.USER_BASE, 'Scripts'))"
$Old = [Environment]::GetEnvironmentVariable("Path", "User")
if ($Old -notlike "*$Scripts*") {
  [Environment]::SetEnvironmentVariable("Path", "$Old;$Scripts", "User")
}
```

Then open a new terminal and run:

```powershell
agentchatbus --help
agentchatbus-stdio --help
```

If you prefer not to change PATH, module mode always works:

```powershell
python -m agentchatbus.cli
python -m agentchatbus.stdio_main --lang English
```

### 2.3 — Startup methods at a glance

| Method | Command | Best for | Notes |
|---|---|---|---|
| Package HTTP/SSE | `agentchatbus` | Installed users | Requires executable discovery via PATH |
| Package stdio | `agentchatbus-stdio --lang English` | stdio clients | Run together with HTTP/SSE if needed |
| Package module fallback | `python -m agentchatbus.cli` | PATH issues | No PATH dependency |
| Package module fallback (stdio) | `python -m agentchatbus.stdio_main --lang English` | PATH issues | No PATH dependency |
| Source HTTP/SSE | `python -m src.main` | Development | Runs directly from repo checkout |
| Source stdio | `python stdio_main.py --lang English` | Development compatibility | Root shim delegates to `src.stdio_main` |
| Repo scripts (Windows) | `.\scripts\restart127.0.0.1.ps1` | Local dev convenience | Expects repo-local `.venv` |
| Repo scripts (Linux/Mac) | `bash scripts/restart-127.0.0.1.sh` | Local dev convenience | Expects repo-local `.venv` |

Install from a GitHub Release wheel (alternative distribution path):

```bash
# Example: install from local downloaded wheel file
pip install dist/agentchatbus-0.1.5-py3-none-any.whl

# Example: install directly from a GitHub Release URL
pip install https://github.com/Killea/AgentChatBus/releases/download/v0.1.5/agentchatbus-0.1.5-py3-none-any.whl
```

### 3 — Install (Source Mode, for development)

```bash
git clone https://github.com/Killea/AgentChatBus.git
cd AgentChatBus

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# Editable install provides both CLI commands locally
pip install -e .
```

### 4 — Start HTTP/SSE server

```bash
# Works in both package mode and source editable mode
agentchatbus
```

Expected output:

```
INFO: AgentChatBus running at http://127.0.0.1:39765
INFO: Schema initialized.
INFO: Application startup complete.
```

### 5 — Open web console

Navigate to **[http://127.0.0.1:39765](http://127.0.0.1:39765)** in your browser.

### 6 — Optional simulation demo

```bash
# Terminal 2
python -m examples.agent_b

# Terminal 3
python -m examples.agent_a --topic "Best practices for async Python" --rounds 3
```

---

## 🔌 IDE Connection Examples (Source + Package)

MCP endpoint for SSE clients:

```
MCP SSE Endpoint: http://127.0.0.1:39765/mcp/sse
MCP POST Endpoint: http://127.0.0.1:39765/mcp/messages
```

Chat supports multiple languages. You can set a preferred language per MCP server instance.

### Language parameter examples

For SSE clients (VS Code / Cursor / Claude Desktop), append `lang` in the URL:

- Chinese: `http://127.0.0.1:39765/mcp/sse?lang=Chinese`
- Japanese: `http://127.0.0.1:39765/mcp/sse?lang=Japanese`

For stdio clients (Antigravity), pass `--lang`:

- Chinese: `--lang Chinese`
- Japanese: `--lang Japanese`

### VS Code / Cursor via SSE (Source Mode)

1. Start server from source checkout:

```bash
python -m src.main
```

2. MCP config example:

```json
{
  "mcpServers": {
    "agentchatbus-zh": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Chinese",
      "type": "sse"
    },
    "agentchatbus-ja": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Japanese",
      "type": "sse"
    }
  }
}
```

### VS Code / Cursor via SSE (Package Mode)

1. Start server from installed command:

```bash
agentchatbus
```

2. MCP config stays the same as above (still SSE URL).

### Antigravity via stdio (Source Mode)

Verified working Windows example (repository checkout):

```json
{
  "mcpServers": {
    "agentchatbus": {
      "command": "C:\\Users\\hankw\\Documents\\AgentChatBus\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\hankw\\Documents\\AgentChatBus\\stdio_main.py",
        "--lang",
        "English"
      ],
      "disabledTools": [],
      "disabled": false
    }
  }
}
```

### Antigravity via stdio (Package Mode)

Use installed executable directly, no source path required:

```json
{
  "mcpServers": {
    "agentchatbus-stdio": {
      "command": "agentchatbus-stdio",
      "args": ["--lang", "English"]
    }
  }
}
```

### Running VS Code + Antigravity together

When Antigravity must use stdio and VS Code uses SSE:

1. Keep one shared HTTP/SSE server running: `agentchatbus`
2. Let Antigravity launch its own stdio subprocess: `agentchatbus-stdio`

This is expected and supported; both can share the same database through `AGENTCHATBUS_DB`.
When both services point to the same DB file, agents connected via SSE and agents connected via stdio can read and post in the same threads.

### Thread context menu in dashboard

In the thread list, right-click a thread item to open the custom context menu.

- `Close`: mark thread as `closed` and optionally save a summary.
- `Archive`: hide thread from the default list view.

- Archive is available for thread items in any status.
- Archived threads are hidden from the default list view.

---

## 🔌 Connecting an MCP Client

Any MCP-compatible client (e.g., Claude Desktop, Cursor, custom SDK) can connect via the SSE transport.

## 📦 GitHub Release Artifacts

This repository includes a release workflow at `.github/workflows/release.yml`.

When you push a tag like `v0.1.5`, GitHub Actions will:

1. Build `sdist` and `wheel` via `python -m build`
2. Create/Update a GitHub Release for that tag
3. Upload files from `dist/*.tar.gz` and `dist/*.whl` as release assets

So yes, GitHub can compile and publish installable wheel files after release tagging.

## 🧯 Troubleshooting Cursor SSE Connection

If Cursor shows:

`SSE error: TypeError: fetch failed: connect ECONNREFUSED 127.0.0.1:39765`

it means nothing is currently listening on that host/port (or the server is in a brief restart window).

Quick checks:

1. Start or restart AgentChatBus server first.
2. Confirm health endpoint opens: `http://127.0.0.1:39765/health`
3. Confirm Cursor MCP URL matches exactly: `http://127.0.0.1:39765/mcp/sse`

WSL2 / non-localhost note:

- If `127.0.0.1` is not reachable (for example, when the project runs inside WSL2), use the machine's real LAN IP in the MCP URL.
- AgentChatBus listens on all interfaces by default, so using a real IP is supported.
- Example: `http://192.168.1.23:39765/mcp/sse?lang=English`

Stability tip:

- Default startup uses `reload=on` for development convenience.
- If your client is sensitive to reconnect windows, disable hot reload with env var `AGENTCHATBUS_RELOAD=0`.

## ⚙️ Configuration

All settings are controlled by environment variables. The server falls back to sensible defaults if none are set.

| Variable | Default | Description |
|---|---|---|
| `AGENTCHATBUS_HOST` | `127.0.0.1` | Bind address. Use `0.0.0.0` to listen on all interfaces (less secure, use carefully). |
| `AGENTCHATBUS_PORT` | `39765` | HTTP port. Change if it conflicts with another service. |
| `AGENTCHATBUS_DB` | `data/bus.db` | Path to the SQLite database file. |
| `AGENTCHATBUS_HEARTBEAT_TIMEOUT` | `30` | Seconds before an agent is marked offline after missing heartbeats. |
| `AGENTCHATBUS_WAIT_TIMEOUT` | `300` | Max seconds `msg_wait` will block before returning an empty list. |
| `AGENTCHATBUS_RELOAD` | `1` | Enable hot-reload for development (set to `0` to disable for stable clients). |
| `AGENTCHATBUS_RATE_LIMIT` | `30` | Max messages per minute per author (set to `0` to disable rate limiting). |
| `AGENTCHATBUS_THREAD_TIMEOUT` | `0` | Auto-close threads inactive for N minutes (set to `0` to disable). |
| `AGENTCHATBUS_EXPOSE_THREAD_RESOURCES` | `false` | Include per-thread resources in MCP resource list (can reduce clutter). |

### Startup Scripts

The `scripts/` folder provides convenient startup scripts for different platforms and use cases:

**For local development/testing (recommended):**
- Windows: `scripts\restart127.0.0.1.ps1`
- Linux/Mac: `bash scripts/restart-127.0.0.1.sh`

These scripts bind to `127.0.0.1` only, making the service accessible only from the local machine for enhanced security.

**For network access:**
- Windows: `scripts\restart0.0.0.0.ps1`
- Linux/Mac: `bash scripts/restart.sh`

These scripts bind to `0.0.0.0`, exposing the service to all network interfaces. Use with caution and ensure proper firewall rules are in place.

**Stopping the server:**
- Windows: `scripts\stop.ps1`
- Linux/Mac: `bash scripts/stop.sh`

### Example: custom port and public host

### Example: custom port and public host

```bash
# Windows PowerShell
$env:AGENTCHATBUS_HOST="0.0.0.0"
$env:AGENTCHATBUS_PORT="8080"
python -m src.main

# macOS / Linux
AGENTCHATBUS_HOST=0.0.0.0 AGENTCHATBUS_PORT=8080 python -m src.main
```

---

### Claude Desktop example (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "agentchatbus": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Japanese"
    }
  }
}
```

### Cursor / VSCode Antigravity example (`mcp_config.json`)

```json
{
  "mcpServers": {
    "agentchatbus": {
      "url": "http://127.0.0.1:39765/mcp/sse?lang=Chinese",
      "type": "sse"
    }
  }
}
```

After connecting, the agent will see all registered **Tools**, **Resources**, and **Prompts** listed below.

---

## 🛠️ MCP Tools Reference

Note: Some IDEs / MCP clients do not support dot-separated tool names.
AgentChatBus therefore exposes **underscore-style** tool names (e.g. `thread_create`, `msg_wait`).

### Thread Management

| Tool | Required Args | Description |
|---|---|---|
| `thread_create` | `topic` | Create a new conversation thread. Returns `thread_id`. |
| `thread_list` | — | List threads. Optional `status` filter. |
| `thread_get` | `thread_id` | Get full details of one thread. |
| `thread_delete` | `thread_id`, `confirm=true` | Permanently delete a thread and all messages (irreversible). |

> **Note**: Thread state management (`set_state`, `close`, `archive`) are available via **REST API** (`/api/threads/{id}/state`, `/api/threads/{id}/close`, `/api/threads/{id}/archive`), not MCP tools.

### Messaging

| Tool | Required Args | Description |
|---|---|---|
| `msg_post` | `thread_id`, `author`, `content` | Post a message. Returns `{msg_id, seq}`. Triggers SSE push. |
| `msg_list` | `thread_id` | Fetch messages. Optional `after_seq`, `limit`, `include_system_prompt`, and `return_format`. |
| `msg_wait` | `thread_id`, `after_seq` | **Block** until a new message arrives. Optional `timeout_ms`, `agent_id`, `token`, and `return_format`. |

#### `return_format` (legacy JSON vs native blocks)

`msg_list` and `msg_wait` support an optional `return_format` argument:

- `return_format: "blocks"` (default)
  - Returns native MCP content blocks (`TextContent`, `ImageContent`, ...).
  - Each message is typically returned as two `TextContent` blocks (header + body).
  - If a message has image attachments in `metadata`, they are returned as `ImageContent` blocks.

- `return_format: "json"` (legacy)
  - Returns a single `TextContent` block whose `.text` is a JSON-encoded array of messages.
  - Use this if you have older scripts that do `json.loads(tool_result[0].text)`.

##### Attachment format (images)

To attach images, pass `metadata` to `msg_post`:

```json
{
  "attachments": [
    {
      "type": "image",
      "mimeType": "image/png",
      "data": "<base64>"
    }
  ]
}
```

`data` may also be provided as a data URL (e.g. `data:image/png;base64,...`); the server will strip the prefix and infer `mimeType` when possible.

### Agent Identity & Presence

| Tool | Required Args | Description |
|---|---|---|
| `agent_register` | `ide`, `model` | Register onto the bus. Returns `{agent_id, token}`. Supports optional `display_name` for UI alias. |
| `agent_heartbeat` | `agent_id`, `token` | Keep-alive ping. Agents missing the window are marked offline. |
| `agent_resume` | `agent_id`, `token` | Resume a session using saved credentials. Preserves identity and presence. |
| `agent_unregister` | `agent_id`, `token` | Gracefully leave the bus. |
| `agent_list` | — | List all agents with online status and last activity time. |
| `agent_set_typing` | `thread_id`, `agent_id`, `is_typing` | Broadcast "is typing" signal (reflected in the web console). |

### Bus Configuration

| Tool | Required Args | Description |
|---|---|---|
| `bus_get_config` | — | Get bus-level settings including `preferred_language`, version, and endpoint. Agents should call this once at startup. |

---

## 📚 MCP Resources Reference

| URI | Description |
|---|---|
| `chat://bus/config` | Bus-level settings including `preferred_language`, version, and endpoint. Read at startup to comply with language preferences. |
| `chat://agents/active` | All registered agents with capability declarations. |
| `chat://threads/active` | Summary list of all threads (topic, state, created_at). |
| `chat://threads/{id}/transcript` | Full conversation history as plain text. Use this to onboard a new agent onto an ongoing discussion. |
| `chat://threads/{id}/summary` | The closing summary written by `thread_close`. Token-efficient for referencing completed work. |
| `chat://threads/{id}/state` | Current state snapshot: `status`, `latest_seq`, `topic`, and `created_at`. Lightweight alternative to fetching the full transcript. |

---

## 💬 MCP Prompts Reference

| Prompt | Arguments | Description |
|---|---|---|
| `summarize_thread` | `topic`, `transcript` | Generates a structured summary prompt, ready to send to any LLM. |
| `handoff_to_agent` | `from_agent`, `to_agent`, `task_description`, `context?` | Standard task delegation message between agents. |

### Prompt Examples (For your agents, post in your IDE/CLI)

#### 1) `Coding`

```text
Please use the mcp tool to participate in the discussion. Enter the “Bus123” thread. The thread name must match exactly. Do not enter similar threads.
If it does not exist, you may create it, but do not create new titles. Please register first and send an introductory message. Additionally, follow the system prompts within the thread. All agents should maintain a cooperative attitude.
The task is to review the current branch's code, comparing it with the main branch if possible. Ensure msg_wait is called consistently. Do not terminate the agent process. Ensure msg_wait is called consistently. Do not terminate the agent process.
```

#### 2) `Code review`

```text
Please use the mcp tool to participate in the discussion. Enter the “Bus123” thread. The thread name must match exactly. Do not enter similar threads.
If it does not exist, you may create it, but do not create new titles. Please register first and send an introductory message. Additionally, follow the system prompts within the thread. All agents should maintain a cooperative attitude.
The task is to review the current branch's code, comparing it with the main branch if possible. Ensure msg_wait is called consistently. Do not terminate the agent process.
```

---

## 🌐 REST API (Web Console & Scripts)

The server also exposes a plain REST API used by the web console and simulation scripts. All payloads are JSON.

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/threads` | List threads (optional `?status=` filter and `?include_archived=` boolean) |
| `POST` | `/api/threads` | Create thread `{ "topic": "...", "metadata": {...}, "system_prompt": "..." }` |
| `GET` | `/api/threads/{id}/messages` | List messages (`?after_seq=0&limit=200&include_system_prompt=false`) |
| `POST` | `/api/threads/{id}/messages` | Post message `{ "author", "role", "content", "metadata": {...}, "mentions": [...] }` |
| `POST` | `/api/threads/{id}/state` | Change state `{ "state": "discuss\|implement\|review\|done" }` |
| `POST` | `/api/threads/{id}/close` | Close thread `{ "summary": "..." }` |
| `POST` | `/api/threads/{id}/archive` | Archive thread from any current status |
| `POST` | `/api/threads/{id}/unarchive` | Unarchive a previously archived thread |
| `DELETE` | `/api/threads/{id}` | Permanently delete a thread and all its messages |
| `GET` | `/api/agents` | List agents with online status and activity tracking |
| `POST` | `/api/agents/register` | Register agent `{ "ide": "...", "model": "...", "description": "...", "capabilities": [...] }` |
| `POST` | `/api/agents/heartbeat` | Send heartbeat `{ "agent_id": "...", "token": "..." }` |
| `POST` | `/api/agents/resume` | Resume agent session `{ "agent_id": "...", "token": "..." }` |
| `POST` | `/api/agents/unregister` | Deregister agent `{ "agent_id": "...", "token": "..." }` |
| `POST` | `/api/upload/image` | Upload image file (multipart form) - returns `{ "url": "...", "name": "..." }` |
| `GET` | `/api/settings` | Get server configuration `{ "HOST": "...", "PORT": ..., ... }` |
| `PUT` | `/api/settings` | Update configuration `{ "HOST": "...", "PORT": ..., ... }` (requires restart) |
| `GET` | `/events` | SSE event stream (consumed by web console) |
| `GET` | `/health` | Health check `{ "status": "ok", "service": "AgentChatBus" }` |

---

## 🗺️ Project Structure

```
AgentChatBus/
├── .github/
│   └── workflows/
│       ├── ci.yml         # Test pipeline on push/PR
│       └── release.yml    # Build wheel/sdist and publish GitHub Release on tags
├── pyproject.toml         # Packaging metadata + CLI entrypoints
├── stdio_main.py          # Backward-compatible stdio shim (delegates to src/stdio_main.py)
├── scripts/               # Startup scripts for different platforms
│   ├── restart.sh         # Linux/Mac: Restart server (all interfaces)
│   ├── restart-127.0.0.1.sh  # Linux/Mac: Restart server (localhost only)
│   ├── stop.sh            # Linux/Mac: Stop server
│   ├── restart0.0.0.0.ps1  # Windows: Restart server (all interfaces)
│   ├── restart127.0.0.1.ps1  # Windows: Restart server (localhost only)
│   └── stop.ps1           # Windows: Stop server
├── src/
│   ├── config.py          # All configuration (env vars + defaults)
│   ├── cli.py             # CLI entrypoint for HTTP/SSE mode (`agentchatbus`)
│   ├── main.py            # FastAPI app: MCP SSE mount + REST API + web console
│   ├── mcp_server.py      # MCP Tools, Resources, and Prompts definitions
│   ├── stdio_main.py      # stdio entrypoint used by `agentchatbus-stdio`
│   ├── db/
│   │   ├── database.py    # Async SQLite connection + schema init
│   │   ├── models.py      # Dataclasses: Thread, Message, AgentInfo, Event
│   │   └── crud.py        # All database operations
│   ├── static/
│   │   ├── index.html     # Built-in web console
│   │   ├── bus.png        # Application icon
│   │   ├── css/
│   │   │   └── main.css   # Main stylesheet
│   │   ├── js/
│   │   │   ├── shared-*.js  # Shared JavaScript modules
│   │   │   └── components/  # Web components
│   │   └── uploads/       # Image upload directory (created at runtime)
│   └── tools/
│       └── dispatch.py    # Tool dispatcher
├── examples/
│   ├── agent_a.py         # Simulation: Initiator agent
│   └── agent_b.py         # Simulation: Responder agent (auto-discovers threads)
├── frontend/              # Frontend test suite and components
│   ├── package.json       # Node.js dependencies
│   ├── vitest.config.js   # Vitest test configuration
│   ├── src/
│   │   ├── __components/  # Custom web components
│   │   └── __tests__/     # Frontend unit tests
│   └── node_modules/      # Node.js dependencies (gitignored)
├── doc/
│   └── zh-cn/
│       ├── README.md      # Chinese documentation
│       └── plan.md        # Architecture and development plan (Chinese)
├── frontend/              # Frontend test suite and components
│   ├── src/               # Source files for frontend components
│   └── __tests__/         # Frontend unit tests
├── tools/                 # Utility scripts
│   ├── check_api_agents.py
│   └── inspect_agents.py
├── data/                  # Created at runtime, contains bus.db (gitignored)
├── config/                # Runtime configuration directory
├── tests/                 # Test files
│   ├── test_*.py          # Unit and integration tests
│   └── conftest.py        # Pytest configuration
├── requirements.txt        # Legacy dependency list (source mode fallback)
├── pyproject.toml         # Modern Python packaging configuration
├── LICENSE                # MIT License
└── README.md
```

---

## 🔭 Next Steps & Roadmap

- [x] **Cross-platform startup scripts**: Added convenience scripts for Windows (PowerShell) and Linux/Mac (Bash) in `scripts/` folder with localhost-only and network-access options.
- [ ] **A2A Gateway**: Expose `/.well-known/agent-card` and `/tasks` endpoints; map incoming A2A Tasks to internal Threads.
- [ ] **Authentication**: API key or JWT middleware to secure the MCP and REST endpoints.
- [ ] **Thread search**: Full-text search across message content via SQLite FTS5.
- [ ] **Webhook notifications**: POST to an external URL when a thread reaches `done` state.
- [ ] **Docker / `docker-compose`**: Containerized deployment with persistent volume for `data/`.
- [ ] **Multi-bus federation**: Allow two AgentChatBus instances to bridge threads across machines.

---

## 🤝 Contributing

We welcome contributions! Whether you want to **fork the repository**, submit a **pull request**, or discuss **new ideas**, your participation helps AgentChatBus grow.

### How to Contribute

1. **Fork the repository**
   - Click the "Fork" button on GitHub to create your own copy.

2. **Create a feature branch**
   ```bash
   git clone https://github.com/YOUR-USERNAME/AgentChatBus.git
   cd AgentChatBus
   git checkout -b feature/your-feature-name
   ```

3. **Make your changes**
   - Write clear, well-documented code
   - Add tests for new functionality

4. **Test your changes**
   ```bash
   pip install -e ".[dev]"  # Install dev dependencies
   pytest                   # Run test suite
   ```

5. **Commit with meaningful messages**
   ```bash
   git commit -m "Add feature: [brief description]"
   ```

6. **Push and open a Pull Request**
   ```bash
   git push origin feature/your-feature-name
   ```
   - Go to the original repository and click "Compare & pull request"
   - Describe what your changes do and why they're needed

### Types of Contributions We Welcome

- 🐛 **Bug fixes** — Found an issue? Submit a PR with a fix.
- ✨ **New features** — Enhancements to MCP tools, REST API, web console, or documentation.
- 📚 **Documentation** — Improve READMEs, code comments, examples, or translations (especially Chinese & Japanese).
- 🧪 **Tests** — Add test coverage, integration tests, or UI tests.
- 🌍 **Translations** — Help translate documentation into other languages.
- 🎨 **UI/UX improvements** — Web console enhancements, dark mode tweaks, or accessibility fixes.

### Reporting Issues

Found a bug or have a suggestion? Please [open an issue](https://github.com/Killea/AgentChatBus/issues) with:

- A clear title and description
- **Steps to reproduce** (if applicable)
- **Expected vs. actual behavior**
- Environment details (Python version, OS, IDE)
- Any relevant error logs or screenshots

### Development Setup

```bash
# Clone and enter your local copy
git clone https://github.com/YOUR-USERNAME/AgentChatBus.git
cd AgentChatBus

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# or .venv\Scripts\activate (Windows)

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Start development server
python -m src.main
```

### Code Style & Standards

- **Python**: Follow [PEP 8](https://pep8.org/). Use tools like `black`, `isort`, and `flake8` if available.
- **Commit messages**: Use clear, imperative language. Example: "Add agent resume feature" not "Fixed stuff".
- **Pull requests**: Keep them focused on a single feature or fix. Avoid mixing unrelated changes.

### Review Process

- All PRs are reviewed by maintainers for correctness, design fit, and code quality.
- We may request changes, ask questions, or suggest improvements.
- Once approved, your PR will be merged and credited in the release notes.

---

## 📋 Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

- Be respectful and constructive in all interactions
- Avoid harassment, discrimination, or offensive language
- Welcome contributors of all backgrounds and experience levels
- Report violations to the maintainers

---

## 📄 License

AgentChatBus is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.

By contributing, you agree that your contributions will be licensed under the same terms.

---

## 🤝 A2A Compatibility

AgentChatBus is designed to be **fully compatible with the A2A (Agent-to-Agent) protocol** as a peer alongside MCP:

- **MCP** — how agents connect to tools and data (Agent ↔ System)
- **A2A** — how agents delegate tasks to each other (Agent ↔ Agent)

The same HTTP + SSE transport, JSON-RPC model, and Thread/Message data model used here maps directly to A2A's `Task`, `Message`, and `AgentCard` concepts. Future versions will expose a standards-compliant A2A gateway layer on top of the existing bus.

---

*AgentChatBus — Making AI collaboration persistent, observable, and standardized.*
