Perseus For Slack

License: MIT Slack Agent Builder Challenge

Perseus brings live project context into Slack via MCP — answering "what's running?", "what did we decide?", and "where's that code?" so developer teams ship faster without leaving chat.

Built for the Slack Agent Builder Challenge 2026 (New Slack Agent track) using Perseus MCP server integration.

What it does

• @perseus services — check service health from Slack
• @perseus health — workspace health report (stale checkpoints, duplicate work)
• @perseus checkpoint <task> / @perseus recover — save session state, let anyone on the team pick it up
• @perseus suggest [task] — AI task recommendation via Pythia (local LLM optional, honestly labeled)
• @perseus session [N] — recent session digests
• @perseus memory <topic> — recall team decisions and context
• @perseus search <query> — find code across the project
• @perseus onboard — new team member context dump
• @perseus ask <question> — natural language project queries

Architecture

Dual transport: read-only queries go over MCP; state-changing verbs and the Pythia suggestion engine go through the Perseus CLI.

Slack User → Slack Agent (Bolt) ─┬─ MCP (JSON-RPC 2.0 / HTTP) → Perseus MCP server
                                 │    ├── perseus_services   (health)
                                 │    ├── perseus_get_health (drift, stale/dupe checkpoints)
                                 │    ├── perseus_memory     (Perseus Vault recall)
                                 │    ├── perseus_session    (session digests)
                                 │    ├── perseus_read       (file inspection)
                                 │    ├── perseus_list    ─┐ code search:
                                 │    ├── perseus_read    ─┘ enumerate + grep (client-side)
                                 │    └── ... 31 tools, auto-generated from the directive registry
                                 └─ CLI subprocess → perseus checkpoint / recover / suggest
                                      └── suggest --llm → any OpenAI-compatible endpoint (optional)

Why MCP

The Slack challenge requires MCP server integration, Slack AI, or Real-Time Search. Perseus ships as a production MCP server whose directive registry auto-generates 31 tools (measured via tools/list) with zero per-tool schema wiring — we're wiring real infrastructure into Slack, not building a toy.

AI suggestions — no GPU required

@perseus suggest runs Pythia, the Perseus tool oracle. Two modes, always labeled in the Slack response so nobody mistakes one for the other:

Mode	When	What you see
⚡ Live LLM	PERSEUS_LLM_PROVIDER set	Model's recommendation + provider/model footer
📊 Deterministic	no LLM configured	Keyword-ranked top skills + "no LLM configured" footer

Any OpenAI-compatible endpoint works — all CPU-friendly options:

# Ollama (easiest): ollama pull llama3.2:3b
PERSEUS_LLM_PROVIDER=ollama PERSEUS_LLM_MODEL=llama3.2:3b PERSEUS_LLM_URL=http://localhost:11434

# llama.cpp / LM Studio / Lemonade / vLLM — anything serving /v1/chat/completions
PERSEUS_LLM_PROVIDER=openai-compat PERSEUS_LLM_MODEL=<model-id> PERSEUS_LLM_URL=http://localhost:1234

Quickstart

pip install -r requirements.txt
pip install perseus-ctx               # Perseus MCP server + CLI

# 1. Start the Perseus MCP server from your project directory
perseus mcp serve --transport sse --port 8420   # set mcp.sse_bearer_token in config.yaml

# 2. Run the Slack agent
cp .env.example .env  # fill in SLACK_BOT_TOKEN, SLACK_APP_TOKEN, PERSEUS_MCP_TOKEN
python src/app.py

Project structure

├── src/           # Slack Bolt agent (Python)
│   ├── app.py     # Main app, mentions + slash commands
│   ├── mcp_client.py  # MCP client (Perseus server)
│   ├── handlers.py    # Intent routing
│   └── blocks.py      # Slack Block Kit formatters
├── demo/          # Demo video script + transcript
├── docs/          # Architecture docs + submission
└── assets/        # Architecture diagram

Hackathon

• Challenge: Slack Agent Builder Challenge
• Track: New Slack Agent (MCP server integration)
• Deadline: July 13, 2026
• Prize: $42,000 + Dreamforce trip

License

MIT — LICENSE