コンテンツにスキップ

Slack MCP Agent

4 層パイプラインによる MCP 駆動型業務自動化エージェント。 Slack でメンションするだけで、AI が計画を立て、承認を経て、業務を自動実行します。

アーキテクチャ

User @mention → Slack Bolt → L1 (Task) → L2 (Prompt + 承認)
→ L3 (Process + 承認) → L4 (Managed Agents + MCP) → 完了

詳細は docs/architecture.md を参照。

プロジェクト構成

backend/         Backend (Slack Bolt + Pipeline Orchestrator)
mcp-servers/     Remote MCP Servers (ベンダー別)
  hr-freee/      freee 勤怠・従業員ツール
  common/        Google Sheets・Slack DM 等の共通ツール
shared/          共有スキーマ定義 (ベンダー横断)
web/             Web ダッシュボード (Next.js)
docs/            ドキュメント

セットアップ

前提条件

  • Python 3.12+
  • uv (Python パッケージマネージャ)
  • Node.js 20+ / pnpm (Web ダッシュボード用)
  • ngrok (ローカル開発用トンネル)

環境変数

cp .env.example .env
# .env を編集して各種トークンを設定

Backend

cd backend
uv sync
uv run python -m src.app

MCP Servers

# freee HR MCP Server
cd mcp-servers/hr-freee
uv sync
uv run python server.py

# Common MCP Server
cd mcp-servers/common
uv sync
uv run python server.py

ngrok (開発時)

ngrok start --config ngrok.yml --all

デプロイ (Railway)

単一コンテナ構成で Backend + MCP Server + Web + nginx を Railway にデプロイする。

コンテナ構成

nginx (:$PORT)
  ├── /       → Next.js (:3000)   管理画面
  └── /mcp/   → MCP Server (:8001) Managed Agent 用
Backend (Socket Mode) — インバウンドポート不要
SQLite (/app/data/agent.db) — Railway Volume で永続化

Railway セットアップ手順

  1. Railway でプロジェクト作成、GitHub リポジトリを接続
  2. main ブランチの自動デプロイを有効化
  3. Volume を作成し /app/data にマウント
  4. 環境変数を設定:
変数 説明
SLACK_BOT_TOKEN Slack Bot Token (xoxb-)
SLACK_SIGNING_SECRET Slack Signing Secret
SLACK_APP_TOKEN Slack App-Level Token (xapp-)
ANTHROPIC_API_KEY Anthropic API Key
MOCK_MODE false (本番)
MANAGED_AGENT_ID Managed Agent ID (後述の手順で取得)
MANAGED_ENVIRONMENT_ID Managed Environment ID (後述の手順で取得)
FREEE_CLIENT_ID freee Client ID
FREEE_CLIENT_SECRET freee Client Secret
FREEE_COMPANY_ID freee Company ID
ADMIN_USER 管理画面ユーザー名 (強いものを設定)
ADMIN_PASSWORD 管理画面パスワード (強いものを設定)
BASE_URL https://{app}.up.railway.app
DATABASE_PATH /app/data/agent.db
ENCRYPTION_KEY ランダム生成

  1. freee Developer Console でコールバック URL を追加: https://{app}.up.railway.app/api/integrations/freee/callback

  2. Managed Agent を Railway の MCP Server URL で再作成: 

    MCP_COMBINED_URL=https://{app}.up.railway.app/mcp python scripts/setup-managed-agent.py
    出力された MANAGED_AGENT_ID と MANAGED_ENVIRONMENT_ID を Railway 環境変数に設定。

ローカル Docker ビルド (動作確認用)

docker build -t slack-mcp-agent .
docker run --rm -p 8080:8080 \
  -e PORT=8080 \
  -e MOCK_MODE=true \
  -e SLACK_BOT_TOKEN=xoxb-... \
  -e SLACK_SIGNING_SECRET=... \
  -e SLACK_APP_TOKEN=xapp-... \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e ADMIN_USER=admin \
  -e ADMIN_PASSWORD=admin \
  -e DATABASE_PATH=/app/data/agent.db \
  -v $(pwd)/data:/app/data \
  slack-mcp-agent

ドキュメント

全仕様・設計ドキュメントは docs/ 以下の Markdown に集約されており、MkDocs Material で Web サイトとして自動公開されます（Cloudflare Pages + Cloudflare Access）。

  • ローカルプレビュー: make docs-serve → http://127.0.0.1:8000
  • 本番サイト: main ブランチへのマージで自動デプロイ（.github/workflows/docs.yml）
  • 編集対象: docs/*.md とルートの README.md / AGENTS.md / DESIGN.md

主なドキュメント: