Crystal Agent

LLM agent with MCP (Model Context Protocol) server support.

Installation

Requirements

• Crystal >= 1.19.0
• OpenAI API key (or compatible provider)

Build from source

git clone https://github.com/your-org/crystal_agent.git
cd crystal_agent
shards install
shards build --release

Binary will be at ./bin/crystal_agent.

---

Quick Start

1. Create configuration

mkdir -p ~/.config/crystal_agent
cat > ~/.config/crystal_agent/config.json << 'EOF'
{
  "openaiApiKey": "sk-your-api-key-here",
  "openaiModel": "gpt-4o"
}
EOF

2. Run the agent

./bin/crystal_agent -p "Hello! How are you?"

---

Usage

# Direct prompt
./bin/crystal_agent -p "Your question"

# Prompt from file
./bin/crystal_agent prompt.txt

# Output to file
./bin/crystal_agent -p "Generate a list" -o result.txt

# Interactive mode
./bin/crystal_agent -i

# Specify config
./bin/crystal_agent -p "Question" -c /path/to/config.json

Options

---

Configuration

Agent looks for config in:

1. ~/.config/crystal_agent/config.json
2. ~/.crystal_agent.json

Minimal config

{
  "openaiApiKey": "sk-..."
}

Full config

{
  "openaiApiKey": "sk-...",
  "openaiApiHost": "https://api.openai.com",
  "openaiModel": "gpt-4o",
  "maxIterations": 10,
  "timeoutSeconds": 120,
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Logging is configured via ENV: CRYSTAL_AGENT_LOG_LEVEL (debug/info/warn/error, default warn) and CRYSTAL_AGENT_LOG_FILE.

---

MCP Servers

Agent can connect to MCP servers to use external tools.

HTTP config without "type": "http" is considered invalid. Environment variables can be used as ${VAR} or ${VAR:-default}.

{
  "openaiApiKey": "sk-...",
  "mcpServers": {
    "filesystem": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    },
    "database": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

Stdio MCP server (local process)

{
  "openaiApiKey": "sk-...",
  "mcpServers": {
    "local-tools": {
      "command": "python3",
      "args": ["-u", "/path/to/mcp_server.py"]
    }
  }
}

On startup, the agent automatically connects to servers and registers available tools.

---

Documentation

• USER_GUIDE.md — detailed user guide
• DEVELOPERS_GUIDE.md — for project contributors
• INTEGRATION_GUIDE.md — using as a library

---

License

MIT