🚀 Sean-MCP

PR Automation & GitHub Integration Tool with personality!

A Model Context Protocol (MCP) server and CLI tool for automating GitHub pull request management. Built with TypeScript, Node.js, and pure vibes.

✨ Features

🔀 PR Creation - Create pull requests with auto-generated descriptions
✏️ PR Updates - Update PR descriptions (auto-updates on push!)
📋 PR Listing - List and browse PRs for any repo
🧠 MCP Server - Let Claude manage your PRs for you
🌐 Webhook Server - Auto-update PRs when you push
🎨 Sleek CLI - Beautiful terminal UI with multiple personalities

🚀 Quick Start

1. Install Dependencies

cd seantokuzo-mcp
npm install

2. Configure

# Copy the example env file
cp .env.example .env

# Edit with your GitHub token
# Get one at: https://github.com/settings/tokens

Or run the interactive setup:

npm run cli setup

3. Build

npm run build

4. Use!

CLI Mode:

# Interactive mode
npm run cli

# Specific commands
npm run cli pr create
npm run cli pr update
npm run cli pr list
npm run cli config status

MCP Mode (for Claude): See the MCP Setup section below.

📁 Project Structure

seantokuzo-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # Express webhook server
│   ├── cli/
│   │   ├── index.ts          # CLI entry point
│   │   ├── commands/         # CLI commands (pr, config)
│   │   └── ui/               # Display utilities, messages
│   ├── mcp/
│   │   └── server.ts         # MCP server implementation
│   ├── services/
│   │   └── github.ts         # GitHub API service
│   ├── types/
│   │   └── index.ts          # TypeScript types
│   └── utils/
│       ├── config.ts         # Configuration management
│       └── logger.ts         # Logging utility
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🧠 MCP Setup (For Claude)

The MCP server lets Claude use your PR tools directly. Here's how to set it up:

VS Code with Continue or GitHub Copilot

Add to your MCP settings (.vscode/mcp.json or VS Code settings):

{
  "mcpServers": {
    "sean-mcp": {
      "command": "node",
      "args": ["/path/to/seantokuzo-mcp/dist/mcp/server.js"],
      "env": {
        "GITHUB_TOKEN": "your-github-token",
        "GITHUB_USERNAME": "your-username"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sean-mcp": {
      "command": "node",
      "args": ["/path/to/seantokuzo-mcp/dist/mcp/server.js"],
      "env": {
        "GITHUB_TOKEN": "your-github-token",
        "GITHUB_USERNAME": "your-username"
      }
    }
  }
}

Available MCP Tools

Once configured, Claude can use these tools:

Tool	Description
`create_pull_request`	Create a new PR with auto-generated description
`update_pull_request`	Update a PR's title and/or description
`get_pull_request`	Get details about a specific PR
`list_pull_requests`	List PRs for a repository
`find_pr_for_branch`	Find the PR for a specific branch

🌐 Webhook Server

The webhook server listens for GitHub push events and auto-updates PR descriptions.

Start the Server

npm run start:webhook

Configure GitHub Webhook

Go to your repo → Settings → Webhooks → Add webhook
Payload URL: https://your-server.com/webhook/github
Content type: application/json
Secret: Use the WEBHOOK_SECRET from your .env
Events: Select "Pushes" and "Pull requests"

Local Development

For local testing, use a tool like ngrok:

ngrok http 3847

Then use the ngrok URL as your webhook URL.

🎭 CLI Personalities

The CLI has three personality modes:

🔥 Chaotic (default) - Fun, energetic, memes
💼 Professional - Clean, minimal output
🧘 Zen - Calm, philosophical vibes

Set in your .env:

CLI_PERSONALITY=chaotic  # or: professional, zen

📝 Environment Variables

Variable	Required	Description
`GITHUB_TOKEN`	Yes	GitHub Personal Access Token
`GITHUB_USERNAME`	Yes	Your GitHub username
`WEBHOOK_PORT`	No	Webhook server port (default: 3847)
`WEBHOOK_SECRET`	No	GitHub webhook secret
`CLI_PERSONALITY`	No	CLI personality (chaotic/professional/zen)
`DEFAULT_PR_BASE_BRANCH`	No	Default target branch (default: main)
`DEFAULT_PR_DRAFT`	No	Create draft PRs by default (true/false)

🛠️ Development

# Run CLI in dev mode (with hot reload)
npm run dev:cli

# Run MCP server in dev mode
npm run dev

# Type check
npm run typecheck

# Build
npm run build

🗺️ Roadmap

Future features planned:

Jira Integration - Create/move tickets, manage subtasks
Confluence Integration - Generate documentation
PR Reviewers - Auto-assign reviewers
PR Labels - Auto-apply labels based on changes
AI-Enhanced Descriptions - Use AI for better PR descriptions

Built with 🔥 and TypeScript

Sean-MCP