# 🚀 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
```bash
cd seantokuzo-mcp
npm install
```
### 2. Configure
```bash
# 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:
```bash
npm run cli setup
```
### 3. Build
```bash
npm run build
```
### 4. Use!
**CLI Mode:**
```bash
# 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):
```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"
}
}
}
}
```
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```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
```bash
npm run start:webhook
```
### Configure GitHub Webhook
1. Go to your repo → Settings → Webhooks → Add webhook
2. **Payload URL:** `https://your-server.com/webhook/github`
3. **Content type:** `application/json`
4. **Secret:** Use the `WEBHOOK_SECRET` from your `.env`
5. **Events:** Select "Pushes" and "Pull requests"
### Local Development
For local testing, use a tool like [ngrok](https://ngrok.com/):
```bash
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
```bash
# 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_
