AI Assistant with MCP Tools

A flexible AI assistant that integrates with Model Context Protocol (MCP) servers, built with pydantic-ai and Anthropic's Claude.

Features

• 🤖 Natural language interface powered by Claude
• 🔧 MCP tool integration for extended capabilities
• ⚡ Fast startup with persistent command history
• 🎨 Customizable personality via system prompt
• 🛡️ Type-safe with pydantic validation throughout

Installation

Requires Python 3.11+ and uv.

# Clone the repository
git clone <repository-url>
cd assistant

# Install dependencies
uv sync

# Copy environment variables
cp .env.example .env
# Edit .env with your Anthropic API key

# Copy and configure MCP servers (IMPORTANT: Never commit servers.json)
cp etc/servers.json.example etc/servers.json
# Edit etc/servers.json with your MCP server paths and credentials

# Setup pre-commit hooks (optional but recommended)
uv run pre-commit install

Configuration

1. API Key: Set ANTHROPIC_API_KEY in .env
2. System Prompt: Edit etc/system_prompt.txt to define the assistant's personality
3. MCP Servers: Configure in etc/servers.json

Usage

CLI Mode

# Run the assistant
uv run obiwan-cli

# Available commands
help    - Show available commands
status  - Show MCP server status
clear   - Clear the screen
reset   - Reset conversation context
exit    - Exit the application

Type any natural language query and the assistant will respond, using MCP tools when appropriate.

Slack Bot Mode

First, configure your Slack app:

1. Create a Slack app at https://api.slack.com/apps
2. Enable Socket Mode under "Socket Mode" settings
3. Add Bot Token Scopes: chat:write, channels:history, groups:history, im:history, mpim:history, app_mentions:read, commands
4. Install the app to your workspace
5. Copy the Bot User OAuth Token (starts with xoxb-)
6. Copy the App-Level Token (starts with xapp-)

Set the following environment variables in your .env file:

SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here

# Run the Slack bot
uv run obiwan-slack

# Or with custom env file
uv run obiwan-slack --env-file .env.production

The bot supports:

• Direct messages
• @mentions in channels
• Thread-aware conversations

MCP Servers

This assistant can connect to any MCP-compatible server. Configure servers in etc/servers.json:

{
  "mcpServers": {
    "example": {
      "command": "command-to-start-server",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Additional Tools

# Analyze MCP server tool responses and token usage
uv run obiwan-analyze

Development

# Run code quality checks
uv run ruff check src/ && uv run mypy src/

# Auto-fix linting issues
uv run ruff check src/ --fix

# Format code
uv run ruff format src/

For detailed development guidelines, architecture overview, and contribution instructions, see CLAUDE.md.

License

MIT License - see LICENSE file for details.