Bale Codex

Python MCP server and Bale chat bridge for AI-assisted chat automation.

Bale_Codex is an experimental Python project that connects Bale chats to AI-assisted development workflows.

It provides a small bridge for reading registered Bale chats, sending messages, handling selected file attachments, and exposing chat operations through an MCP server so tools such as Codex-compatible agents can interact with Bale conversations in a structured way.

Status: Experimental / active development This project is currently focused on local automation workflows and MCP integration. The API and internal structure may change as the project evolves.

---

Why this exists

Messaging apps are often used as lightweight workspaces for:

• Project notes
• Task discussions
• File sharing
• Code snippets
• Bot-based automation
• Human-to-agent workflows

Bale_Codex explores how Bale chats can be connected to AI tools through a local MCP server.

The goal is to make it possible for an AI assistant or coding agent to safely inspect selected chat history, read supported file attachments, and send messages through a controlled interface.

---

What this project does

Bale_Codex is designed around three main capabilities:

1. Bale chat access

   • Register Bale chats
   • List registered chats
   • Read recent messages from selected chats
   • Send messages to selected chats

2. MCP integration

   • Expose Bale-related operations as MCP tools
   • Allow AI tools to interact with registered Bale chats
   • Keep the MCP entrypoint thin and modular

3. File-aware message handling

   • Read supported text and document attachments
   • Return metadata for unsupported files
   • Avoid crashing on malformed or unsupported message payloads

---

Current Features

• Bale bot entrypoint using aiobale
• Chat registration flow
• Message reading from registered chats
• Message sending service
• MCP server entrypoint
• Modular service-based structure
• Basic file/document handling structure
• Safe fallback behavior for unsupported content
• Codex-oriented project notes under .codex/

---

Planned MCP Tools

The project is designed to expose tools such as:

bale_list_chats
bale_read_messages
bale_send_message

These tools are intended to let an AI agent:

• List available registered chats
• Read recent messages from a known chat
• Send a message to a known chat
• Receive structured warnings when a message or attachment cannot be fully processed

---

Project Structure

Current high-level structure:

Bale_Codex/
├── .codex/
├── handlers/
├── interfaces/
│   ├── mcp_support/
│   └── mcp_server.py
├── scripts/
├── services/
│   ├── documents/
│   ├── chat_lookup.py
│   ├── chat_messages.py
│   ├── chat_registry.py
│   ├── document_reader.py
│   ├── exporter.py
│   ├── get_messages.py
│   └── send_message.py
├── utils/
├── bot.py
├── requirements.txt
└── README.md

The structure is intentionally split by responsibility:

• interfaces/ — external entrypoints such as MCP server integration
• handlers/ — Bale bot command handlers
• services/ — business logic for chats, messages, exports, and sending
• services/documents/ — document and attachment-related handling
• utils/ — shared helper functions
• .codex/ — project notes and context for AI-assisted development

---

Installation

Clone the repository:

git clone https://github.com/pouryawJs/Bale_Codex.git
cd Bale_Codex

Create and activate a virtual environment:

python -m venv .venv

On macOS/Linux:

source .venv/bin/activate

On Windows:

.venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

---

Requirements

The project currently depends on:

mcp>=1.2.0
aiobale

Additional document parsing dependencies may be added as file support becomes more complete.

---

Usage

Run the Bale bot

python bot.py

The bot currently includes command handling for chat registration and analysis-related workflows.

Run the MCP server

python -m interfaces.mcp_server

The MCP server is intended to expose Bale chat operations to AI tools.

---

Example MCP Workflow

A typical future workflow may look like this:

1. Register a Bale chat through the bot.
2. Start the local MCP server.
3. Connect an AI coding assistant to the MCP server.
4. Ask the assistant to read recent messages from a registered chat.
5. Ask the assistant to summarize the discussion or send a reply.

Example tool-style calls:

bale_list_chats()

bale_read_messages(
    chat_title="project discussion",
    limit=10
)

bale_send_message(
    chat_title="project discussion",
    text="Summary generated successfully."
)

---

File Handling

The project is designed to support safe file-aware message processing.

Planned or partial support includes:

Text and code files

.txt
.md
.json
.csv
.py
.js
.ts
.html
.css
.xml
.yaml
.yml
.log

Documents

.pdf
.docx
.xlsx

Unsupported files

Unsupported files such as archives, images, videos, and audio files should be handled safely with metadata-only output instead of crashing the MCP flow.

Examples:

.zip
.rar
.png
.jpg
.mp4
.mp3

---

Safety and Limitations

This project is experimental and should be used carefully.

Current limitations:

• Not production-ready
• MCP tool contracts may change
• Authentication and access control should be reviewed before wider usage
• File extraction support may be incomplete
• Unsupported file types should be treated as metadata-only
• Live Bale behavior depends on aiobale and the configured bot/session environment

Recommended usage:

• Use in local or controlled environments
• Avoid exposing the MCP server publicly
• Do not send sensitive chats to untrusted AI tools
• Keep chat registration explicit and limited

---

Development Notes

The project is being developed with a modular structure so each part can evolve independently:

• MCP interface logic should stay thin
• Chat/message business logic should live in services/
• Bale command handling should live in handlers/
• File parsing should stay isolated from MCP tool definitions
• Unsupported or malformed messages should return warnings instead of crashing

---

Testing

A formal test suite is not fully established yet.

Suggested manual checks:

• Run the Bale bot successfully
• Register a test chat
• List registered chats through the MCP server
• Read recent messages from a registered chat
• Send a test message to a registered chat
• Test behavior with unsupported attachments
• Confirm malformed messages do not crash the flow

Future testing goals:

• Unit tests for chat registry logic
• Unit tests for message serialization
• Unit tests for document/file handling
• MCP tool contract tests
• Smoke tests for local MCP server behavior

---

Roadmap

Planned improvements:

• Add clear MCP tool documentation
• Add .env.example for required runtime settings
• Add structured message serializers
• Add safer access-control rules for chat operations
• Add tests for services and MCP tools
• Improve file extraction support
• Add better logs and warnings
• Add examples for Codex-compatible MCP setup
• Add a small demo workflow in the README

---

Related Projects

Other active open-source projects by the maintainer:

• maintainer-agent-kit — GitHub Action and CLI toolkit for OSS maintainer automation.
• telegram-bot-frame — Early-stage TypeScript CLI scaffolding tool for Telegram bot projects.

---

Contributing

This project is still experimental, but feedback and ideas are welcome.

Good areas for contribution:

• MCP tool documentation
• Message serialization improvements
• File handling improvements
• Tests
• Error handling
• Example workflows
• Setup documentation

---

License

MIT