dbbaskette/RepoMan

🚀 RepoMan

📋 Overview

RepoMan is a Streamable HTTP Model Context Protocol (MCP) server powered by the Embabel Agent Framework. It uses Goal-Oriented Action Planning (GOAP) to autonomously manage Git repositories with zero manual intervention.

Simply invoke repoman /path/to/workspace from Claude Code or any MCP client, and watch as RepoMan:

All steps are performed autonomously using intelligent planning powered by Embabel's GOAP engine!

✨ Key Features

• 🤖 Embabel GOAP Agent - Intelligent action planning with preconditions and effects
• 🌐 Streamable HTTP MCP - Modern protocol for AI-agent communication
• 🔧 Spring Boot 3.5.6 - Production-ready Java framework
• 🐙 GitHub Integration - Automatic repository creation via API
• 🔐 Secure by Default - .env file pattern, no secrets in code
• 🧪 Fully Tested - Comprehensive unit and integration tests
• 📊 Type-Safe Configuration - Spring Boot configuration properties
• 🚀 Zero Configuration - Works out of the box with sensible defaults

🏗️ Architecture

┌─────────────────────────────────────────┐
│  Claude Code / MCP Client               │
│  "repoman /path/to/workspace"           │
└──────────────┬──────────────────────────┘
               │
               │ Streamable HTTP (port 8090)
               │
               ▼
┌─────────────────────────────────────────┐
│  Spring Boot MCP Server                 │
│  ┌─────────────────────────────────┐   │
│  │  @McpTool("repoman")            │   │
│  │  • Validates workspace path     │   │
│  │  • Invokes Embabel agent        │   │
│  └─────────────────────────────────┘   │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Embabel Agent (GOAP Engine)            │
│  ┌─────────────────────────────────┐   │
│  │  @Agent, @Action, @Condition    │   │
│  │                                 │   │
│  │  Conditions:                    │   │
│  │  ├─ isGitInitialized()          │   │
│  │  ├─ hasUntrackedFiles()         │   │
│  │  ├─ needsCommit()               │   │
│  │  ├─ hasRemote()                 │   │
│  │  └─ isPushed()                  │   │
│  │                                 │   │
│  │  Actions:                       │   │
│  │  ├─ initializeRepository()      │   │
│  │  ├─ stageFiles()                │   │
│  │  ├─ commitChanges()             │   │
│  │  ├─ createAndAddRemote()        │   │
│  │  └─ pushToRemote()              │   │
│  └─────────────────────────────────┘   │
└──────────────┬──────────────────────────┘
               │
               ├──────────┬──────────┐
               ▼          ▼          ▼
          ┌────────┐ ┌────────┐ ┌────────┐
          │  JGit  │ │ GitHub │ │ Spring │
          │  7.1.0 │ │  API   │ │  AI    │
          └────────┘ └────────┘ └────────┘

🚀 Quick Start

Prerequisites

• ☕ Java 17+ (JDK 17, 21, or later)
• 📦 Maven 3.8+
• 🔑 GitHub Personal Access Token with repo scope (Generate here)
• 🤖 OpenAI API Key for Embabel agent (Get key)

1️⃣ Clone and Build

git clone <your-repo-url>
cd RepoMan
mvn clean package

2️⃣ Configure Secrets

RepoMan uses spring-dotenv to securely load environment variables:

cp .env.example .env

Edit .env with your credentials:

# Required
GITHUB_TOKEN=ghp_your_actual_github_token
GITHUB_USER=your-github-username
OPENAI_API_KEY=sk_your_actual_openai_key

# Optional (customize as needed)
GIT_AUTHOR_NAME=Your Name
GIT_AUTHOR_EMAIL=you@example.com

🔒 Security Note: .env is git-ignored. Never commit secrets!

3️⃣ Start the Server

mvn spring-boot:run

Server starts on http://localhost:8090 🎉

4️⃣ Add to Claude Code

In a new terminal:

claude mcp add repoman http://localhost:8090/mcp --transport http

That's it! The server automatically loads secrets from .env.

📚 Detailed Setup: See for troubleshooting and advanced configuration.

🔧 Usage

From Claude Code

Once configured, simply type:

repoman /Users/you/Projects/MyApp

Or for relative paths from your current directory:

repoman this project

Example Interaction

User: repoman this project

Claude: [Invokes MCP tool: repoman]

RepoMan Agent:
✓ Repository initialized
✓ Files staged
✓ Changes committed: a1b2c3d4
✓ Remote added: https://github.com/youruser/MyApp.git
✓ Pushed to remote successfully

Result: ✅ Repository successfully pushed to https://github.com/youruser/MyApp.git

Check Status (Non-Destructive)

repoman-status /path/to/workspace

Returns current Git status without making any changes.

📖 MCP Tools Reference

repoman

Initialize Git repository, commit files, create remote on GitHub, and push.

Returns: Success message with repository URL, or error details.

Example:

repoman /Users/you/Projects/MyNewApp

repoman-status

Check Git status without making changes.

Returns: Current Git status (initialized, has commits, has remote, etc.)

Example:

repoman-status /Users/you/Projects/ExistingApp

⚙️ Configuration

Environment Variables (.env)

* Choose either GITHUB_USER or GITHUB_ORG, not both.

Application Configuration

Edit src/main/resources/application.yml to customize:

spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE    # MCP protocol type
        type: SYNC             # Synchronous execution
    openai:
      chat:
        options:
          model: gpt-4o        # Embabel LLM model
          temperature: 0.7     # Response variability

git:
  default-branch: main
  commit-message: "Initial commit via RepoMan"

server:
  port: 8090                   # Override with SERVER_PORT env var

🧪 Testing

Run All Tests

mvn test

Run Specific Test Class

mvn test -Dtest=GitServiceTest

Run Specific Test Method

mvn test -Dtest=GitServiceTest#testInitRepository_createsGitDirectory

Test Coverage

The test suite includes:

• ✅ Git repository operations (init, add, commit, remote, push)
• ✅ GitHub API integration (create repo, check existence)
• ✅ Spring Boot application context loading
• ✅ Configuration property binding

🛠️ Development

Project Structure

RepoMan/
├── src/main/java/com/example/repoman/
│   ├── agent/                      # 🤖 Embabel GOAP Agent
│   │   ├── RepoManAgent.java       # @Agent with @Action/@Condition
│   │   └── RepoManDomain.java      # Domain model for state
│   ├── config/                     # ⚙️ Configuration
│   │   ├── GitConfig.java          # Git-specific config
│   │   └── GitHubConfig.java       # GitHub API config
│   ├── mcp/                        # 🌐 MCP Tool Endpoints
│   │   └── RepoManTool.java        # @McpTool implementations
│   ├── service/                    # 💼 Business Logic
│   │   ├── GitService.java         # JGit operations
│   │   └── GitHubService.java      # GitHub API client
│   └── RepoManApplication.java     # 🚀 Spring Boot main
├── src/main/resources/
│   └── application.yml             # Configuration
├── src/test/                       # 🧪 Tests
├── .env.example                    # 🔐 Env template
├── .gitignore                      # Git ignore rules
├── MCP_SETUP.md                    # 📚 Setup guide
├── pom.xml                         # Maven build
└── README.md                       # You are here!

Technology Stack

Extending RepoMan

Add new autonomous actions to the Embabel agent:

@Action(description = "Create a pull request on GitHub")
public void createPullRequest(RepoManDomain domain) {
    // Your implementation
    logger.info("Creating pull request for: {}", domain.getRepositoryName());

    // Use GitHub API to create PR
    gitHubService.createPullRequest(
        domain.getRepositoryName(),
        "main",
        "feature-branch",
        "PR created by RepoMan"
    );
}

@Condition
public boolean hasPullRequest(RepoManDomain domain) {
    // Check if PR exists
    return gitHubService.pullRequestExists(domain.getRepositoryName());
}

The GOAP planner will automatically incorporate new actions based on their preconditions and effects!

🔒 Security

Best Practices

✅ DO:

• Use .env for local development secrets
• Use environment variables in production
• Rotate tokens regularly
• Use fine-grained GitHub tokens with minimal scopes
• Keep server on localhost (don't expose publicly)

❌ DON'T:

• Commit .env to version control
• Share tokens in Slack, email, or chat
• Use tokens with excessive permissions
• Hard-code secrets in application code
• Expose MCP server on public internet without authentication

GitHub Token Scopes

Minimum required:

• repo - Create repositories and push code

Optional (for future features):

• workflow - Manage GitHub Actions
• write:packages - Publish packages

Generate at: github.com/settings/tokens

📚 Documentation

Spring AI & MCP

• 📖 MCP Overview - Introduction to Model Context Protocol
• 🔌 MCP Server Starter - Spring Boot integration
• 🌊 Streamable HTTP - HTTP transport protocol
• 🏷️ MCP Annotations - @McpTool reference

Embabel Agent Framework

• 🤖 GitHub Repository - Official Embabel repo
• 📝 Rod Johnson's Introduction - GOAP overview
• 📚 Baeldung Tutorial - Java examples

Model Context Protocol

• 🌐 MCP Specification - Protocol details
• 🔧 MCP SDK - Reference implementation

🐛 Troubleshooting

Server Won't Start

Problem: Port 8090 already in use

Solution: Change port in .env:

SERVER_PORT=8091

Can't Connect from Claude Code

Problem: Connection refused error

Solution: Ensure server is running:

# Check if server is listening
lsof -i :8090

# Restart server if needed
mvn spring-boot:run

Repository Creation Fails

Problem: GitHub token is required error

Solution: Verify token in .env:

# Check token exists and is valid
echo $GITHUB_TOKEN

# Verify scopes at https://github.com/settings/tokens

Permission Denied

Problem: 403 Forbidden from GitHub API

Solution: Regenerate token with repo scope at github.com/settings/tokens

🤝 Contributing

Contributions welcome! Please:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. ✅ Write tests for new functionality
4. 🧪 Ensure all tests pass (mvn test)
5. 📝 Follow Google Java Style Guide
6. 🚀 Submit a pull request

📝 License

This project is licensed under the MIT License - see the file for details.

🙋 Support

Need help?

• 🐛 - Bug reports and feature requests
• 💬 - Questions and community support
• 📖 Check the guide
• 📚 Review Spring AI documentation

🎯 Roadmap

Future enhancements planned:

• Support for multiple Git providers (GitLab, Bitbucket)
• Pull request creation automation
• Branch management (create, merge, delete)
• Commit message templates and validation
• GitHub Actions workflow generation
• Repository settings configuration
• Multi-repository batch operations
• Web UI for monitoring operations

🌟 Acknowledgments

Built with:

• ☕ Spring Boot - The best Java framework
• 🤖 Embabel - Revolutionary GOAP agent framework by Rod Johnson
• 🌐 Spring AI - AI integration for Spring
• 📡 MCP - Model Context Protocol by Anthropic
• 🐙 JGit - Pure Java Git implementation

Special thanks to the Spring and Embabel communities!