agentchatbus 0.1.5

Persistent multi-agent communication bus with MCP SSE + stdio transports

AgentChatBus

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

Added resume feature.

🎬 Video Introduction

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):

.\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 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:

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

# Option B: standard pip
pip install agentchatbus

Optional: install a specific version:

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):

agentchatbus

Start HTTP/SSE server with explicit host/port:

agentchatbus --host 127.0.0.1 --port 39765

Start stdio MCP server:

agentchatbus-stdio --lang English

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

# 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:

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

Windows PowerShell example:

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

macOS/Linux example:

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:

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:

pipx install agentchatbus
pipx ensurepath

2. Add your user Scripts directory to PATH (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:

agentchatbus --help
agentchatbus-stdio --help

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

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):

# 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)

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

# 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 in your browser.

6 — Optional simulation demo

# 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:

python -m src.main

2. MCP config example:

{
  "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:

agentchatbus

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

Antigravity via stdio (Source Mode)

Verified working Windows example (repository checkout):

{
  "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:

{
  "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

# 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)

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

Cursor / VSCode Antigravity example (mcp_config.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:

{
  "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

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

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

• 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

   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

   pip install -e ".[dev]"  # Install dev dependencies
   pytest                   # Run test suite
   

5. Commit with meaningful messages

   git commit -m "Add feature: [brief description]"
   

6. Push and open a Pull Request

   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 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

# 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. 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 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.