rpurinton/architect

Architect

Architect is a modular, AI-empowered Discord.js bot designed for automated Discord server administration and management using the Model Context Protocol (MCP).

Features

• Discord bot with dynamic slash command support and event handling.
• Integrated MCP server exposing Discord admin functions as MCP tools.
• AI-driven natural language automation leveraging OpenAI.
• Localization with multi-language support.
• Robust error handling and graceful shutdown.
• Uses Redis caching and MySQL persistence.
• Secure MCP HTTP interface with bearer token authentication.
• Production-ready with systemd service template.

Quick Start

1. Clone the repo:

   git clone https://github.com/rpurinton/architect.git
   cd architect
   

2. Install dependencies:

   npm install
   

3. Copy and configure environment variables:

   cp .env.example .env
   # Edit .env to set tokens, DB, Redis credentials etc.
   cp tools.json.example tools.json
   # Edit tools.json to configure available tools and MCP servers as needed
   

4. Run:

   node architect.mjs
   

Configuration

Edit .env file to include your Discord bot token, client ID, database credentials, MCP token, and logging preferences.

Configuring Tools and MCP Servers

• The tools.json file defines which tools are available to the AI agent, including web search, image generation, and MCP (Model Context Protocol) servers.
• To add or configure MCP servers, edit the tools array in tools.json. Each entry can specify a different MCP server by setting the server_label, server_url, and headers (such as the Bearer token).
• Important: The server_url for any MCP server must be a publicly reachable URL accessible by OpenAI's API servers. Using localhost or private/internal addresses will not work. Use your server's public/external URL (e.g., https://<external_url>:9232).
• Example:

{
    "tools": [
        {
            "type": "mcp",
            "server_label": "discord",
            "server_url": "https://<external_url>",
            "headers": {
                "Authorization": "Bearer <your-mcp-token>"
            },
            "require_approval": "never"
        }
        // Add more MCP servers here as needed
    ]
}

• For more details, see tools.json.example and the documentation in docs/tool_pattern.md.

Project Structure

/opt/architect
  architect.mjs          # Main app entry point
  src/
    ├── commands/          # JSON command definitions and handlers
    ├── events/            # Event handlers for Discord.js
    ├── custom/            # MCP server, client, and tools
    ├── locales/           # Localization JSON
    ├── log.mjs            # Logger setup
  exceptions.mjs     # Global exception handlers
  shutdown.mjs       # Graceful shutdown handling
  discord.mjs        # Discord client creation

.env                   # Environment variables
architect.service      # systemd service file
└── docs/              # Developer documentationa

Development

• See docs/ for detailed developer documentation.
• Use npm test to run tests.
• Write new commands in src/commands/.
• Add event handlers in src/events/.
• Add MCP tools in src/custom/tools/.

Deployment

• Use the included systemd service for running as a service.
• Ensure .env is correctly configured with all credentials.

Troubleshooting

• Check logs for details, increase LOG_LEVEL for debug.
• Validate Discord bot permissions.
• Check connectivity to database and Redis.

Support & Resources

• Join our Support Discord Server
• Visit our GitHub Project Repository

License

MIT License

Contact

Russell Purinton at russell.purinton@gmail.com Github & Discord: rpurinton

Please see docs/ for comprehensive documentation and contribution guidelines.