GitPasha-MCP-Server/README.md

# 🎯 Overview
#### GitPasha MCP Server is a Model Context Protocol (`MCP`) server that enables Claude Desktop to interact with GitPasha repositories. It provides a comprehensive set of tools for repository management, issue tracking, and pull request operations.
### Key Capabilities:
- 🔐 Secure API authentication
- 📦 Repository `CRUD` operations
- 🐛 Issue management
- 🔀 Pull request creation
- 📝 README file generation
- 🌐 Both local (`stdio`) and cloud (`SSE`) deployment

---

# ✨ Features

- ✅ Repository Management: Create, update, delete repositories
- ✅ Issue Tracking: List, create, update issues with labels and assignees
- ✅ Pull Requests: Open pull requests between branches
- ✅ Auto-suggestions: Smart repository descriptions
- ✅ Flexible Deployment: Local stdio or cloud SSE transport
- ✅ Docker Ready: Containerized for easy cloud deployment
- ✅ Comprehensive Logging: Detailed activity logs for debugging

---

# 📁 Project Structure
```bash
gitpasha-mcp/
├── 📄 main.py                    # Server entry point
├── 📄 Dockerfile                 # Docker configuration
├── 📄 requirements.txt           # Python dependencies
├── 📄 .env                       # Environment variables (create from .env.example)
├── 📄 .env.example              # Environment template
├── 📄 .gitignore                # Git ignore rules
├── 📄 .dockerignore             # Docker ignore rules
├── 📄 README.md                 # This file
│
├── 📂 api/                      # API layer - Direct GitPasha API calls
│   ├── __init__.py
│   ├── 📂 repos/                # Repository operations
│   │   ├── __init__.py
│   │   ├── create.py           # Create repository
│   │   ├── update.py           # Update repository
│   │   └── delete.py           # Delete repository
│   ├── 📂 issues/               # Issue operations
│   │   ├── __init__.py
│   │   ├── list.py             # List issues
│   │   ├── create.py           # Create issue
│   │   └── update.py           # Update issue
│   ├── 📂 pulls/                # Pull request operations
│   │   ├── __init__.py
│   │   └── open.py             # Open pull request
│   └── 📂 files/                # File operations
│       ├── __init__.py
│       └── create_readme.py    # Create README
│
├── 📂 tools/                    # Tools layer - MCP tool wrappers
│   ├── __init__.py
│   ├── repo_create.py          # Repository creation tool
│   ├── repo_update.py          # Repository update tool
│   ├── repo_delete.py          # Repository deletion tool
│   ├── issue_list.py           # Issue listing tool
│   ├── issue_create.py         # Issue creation tool
│   ├── issue_update.py         # Issue update tool
│   └── pr_open.py              # Pull request tool
│
├── 📂 helpers/                  # Helper utilities
│   ├── __init__.py
│   ├── logger.py               # Logging configuration
│   ├── headers.py              # API authentication headers
│   ├── http_client.py          # HTTP client with logging
│   ├── error_formatter.py      # Error message formatting
│   └── descriptions.py         # Repository description suggestions
│
└── 📂 logs/                     # Application logs (auto-created)
    └── gitpasha.log
```

---

# 🔧 Installation
### Prerequisites:
- Python 3.12+ installed
- Git installed
- GitPasha account with API access
- Docker (optional, for cloud deployment)

##### Step 1: Clone the Repository
```bash
git clone https://github.com/YOUR_USERNAME/gitpasha-mcp.git
cd gitpasha-mcp
```

##### Step 2: Create Virtual Environment
```bash
# Windows
python -m venv .venv
.venv\Scripts\activate

# macOS/Linux
python3 -m venv .venv
source .venv/bin/activate
```
##### Step 3: Install Dependencies
```bash
pip install -r requirements.txt
```

---

# ⚙️ Configuration
##### Step 1: Create Environment File
```bash
# Copy the example file
cp .env.example .env
```

##### Step 2: Configure `.env`
**Edit `.env` with your credentials:**
```bash
# GitPasha API Configuration
GITPASHA_API_KEY=your_api_key_here
GITPASHA_BASE_URL=https://app.gitpasha.com/api/v1
GITPASHA__USERNAME=your_username

# Logging Configuration
LOG_LEVEL=DEBUG
LOG_FILE=logs/gitpasha.log

# Server Configuration (for cloud deployment)
MCP_TRANSPORT=stdio          # Use 'stdio' for local, 'sse' for cloud
HOST=0.0.0.0
PORT=8000
```

##### Step 3: Get Your API Key
1. Visit: https://app.gitpasha.com/settings
2. Navigate to API Keys section
3. Generate a new API key
4. Copy and paste into .env


##### Step 4: Create Logs Directory
```bash
mkdir logs
```

---

# 🚀 Running the Server
### Local Development (stdio - for Claude Desktop)
```bash
# Set transport to stdio in .env
MCP_TRANSPORT=stdio

# Run the server
python main.py
```

### You should see:
```bash
INFO | Starting MCP server | BASE_URL=https://app.gitpasha.com/api/v1 | Transport=stdio
```

### Cloud Deployment (SSE - for remote access)
```bash
# Set transport to sse in .env
MCP_TRANSPORT=sse

# Run the server
python main.py
```

You should see:
```bash
INFO | Starting SSE server on 0.0.0.0:8000
INFO | Uvicorn running on http://0.0.0.0:8000
```

---

# 🔍 Testing with Inspector
#### The MCP Inspector is a debugging tool for testing your MCP server.

##### Step 1: Start the Inspector
```bash
npx @modelcontextprotocol/inspector
```

##### Output:
```bash
🚀 MCP Inspector is up and running at:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...
```

##### Step 2: Configure Connection
- For Local (`stdio`):
    - In the Inspector UI:
        - Transport: `stdio`
        - Command: `.venv\Scripts\python.exe` (Windows) or `.venv/bin/python` (macOS/Linux)
        - Args: `main.py`

- For Cloud (`SSE`):
    - In the Inspector UI:
        - Transport: `sse`
        - URL: `http://localhost:8000/sse`

##### Step 3: Test Tools
**Once connected, you'll see all available tools. Try testing:**
###### Create Repository:
```json
{
    "name": "test-repo",
    "description": "Test repository from inspector",
    "private": false
}
```

###### List Issues:
```json
{
    "repo": "test-repo",
    "state": "open"
}
```

---

# 🖥️ Claude Desktop Integration

##### Step 1: Locate Config File

**Windows:**
```bash
%APPDATA%\Claude\claude_desktop_config.json
```

**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Linux:**
```bash
~/.config/Claude/claude_desktop_config.json
```

##### Step 2: Add Server Configuration
**For Local Development (stdio):**
```json
{
    "mcpServers": {
      "gitpasha": {
        "command": "python",
        "args": [
          "C:\\Users\\YOUR_USERNAME\\path\\to\\gitpasha-mcp\\main.py"
        ],
        "env": {
          "MCP_TRANSPORT": "stdio"
        }
      }
    }
}
```

**For Cloud/Remote (SSE):**
```json
{
    "mcpServers": {
      "gitpasha": {
        "url": "https://your-app.ghaymah.systems/sse",
        "transport": "sse"
      }
    }
}
```

##### Step 3: Restart Claude Desktop
**Close and reopen Claude Desktop completely.**

##### Step 4: Verify Connection
**In Claude Desktop, look for the 🔌 hammer icon indicating MCP servers are connected. You should see `"gitpasha"` listed.**

---

# ☁️ Deployment
### Docker Deployment
**Build Image**
```bash
docker build -t gitpasha-mcp:latest .
```

```bash
docker run -p 8000:8000 --env-file .env gitpasha-mcp:latest
```

**Push to Docker Hub**
```bash
# Login
docker login

# Tag
docker tag gitpasha-mcp:latest YOUR_DOCKERHUB_USERNAME/gitpasha-mcp:latest

# Push
docker push YOUR_DOCKERHUB_USERNAME/gitpasha-mcp:latest
```

### Ghaymah Cloud Deployment
1. Visit: https://deploy.ghaymah.systems/
2. Choose: **Deploy from Docker Hub** or **Deploy from GitHub**
3. Configure Environment Variables:
    ```bash
    GITPASHA_API_KEY=your_api_key
    GITPASHA__USERNAME=your_username
    GITPASHA_BASE_URL=https://app.gitpasha.com/api/v1
    MCP_TRANSPORT=sse
    HOST=0.0.0.0
    PORT=8000
    ```
4. Deploy and get your URL!

---

# 🛠️ Available Tools
### 1. `repo_create_tool`
**Create a new repository**
*Parameters:*
- `name` (required): Repository name
- `description` (optional): Repository description
- `private` (optional): Make repository private (default: false)
- `create_readme` (optional): Create README file (default: true)
- `readme_content` (optional): Custom README content

##### Example:
```bash
Create a new repository called "my-api-project"
```

### 2. `repo_update_tool`
**Update repository settings**

*Parameters:*
- `repo` (required): Repository name (e.g., "test-repo" or "username/test-repo")
- `name` (optional): New repository name
- `description` (optional): New description
- `private` (optional): Change privacy setting

##### Example:
```bash
Update repository "test-repo" to have description "Production API"
```

### 3. `repo_delete_tool`
**Delete a repository**

##### Example:
- `repo` (required): Repository name

*Example:*
```bash
Delete repository "old-test-repo"
```

### 4. `issue_list_tool`
**List repository issues**

*Parameters:*
- `repo` (required): Repository name
- `state` (optional): "open", "closed", or "all" (default: "open")

##### Example:
```bash
Show me all open issues in "my-project"
```

5. `issue_create_tool`
**Create a new issue**

*Parameters:*
- `repo` (required): Repository name
- `title` (required): Issue title
- `body` (optional): Issue description
- `labels_csv` (optional): Comma-separated labels
- `assignees_csv` (optional): Comma-separated usernames

##### Example:
```bash
Create an issue in "my-project" titled "Fix login bug" with label "bug"
```

### 6. `issue_update_tool`
**Update an existing issue**

*Parameters:*
- `repo` (required): Repository name
- `issue` (required): Issue number
- `title` (optional): New title
- `body` (optional): New description
- `state` (optional): "open" or "closed"
- `labels_csv` (optional): Update labels
- `assignees_csv` (optional): Update assignees
- `comment` (optional): Add comment to issue

##### Example:
```bash
Close issue #5 in "my-project" and add comment "Fixed in PR #10"
```

7. `pr_open_tool`
**Open a pull request**

*Parameters:*
- `repo` (required): Repository name
- `title` (required): PR title
- `head` (required): Source branch
- `base` (required): Target branch
- `body` (optional): PR description

##### Example:
```bash
Open a pull request in "my-project" from "feature-branch" to "main"
```

---

# 💡 Usage Examples
### Example 1: Create and Initialize Project
```bash
Create a new repository called "awesome-api" with description "RESTful API for awesome app"
```

Claude will:
1. Create the repository
2. Generate a README file
3. Return the repository URL

### Example 2: Manage Issues
```bash
List all open issues in my-project
```

Then:
```bash
Create a new issue in my-project titled "Add authentication" with labels "enhancement,security"
```

Then:
```bash
Update issue #3 in my-project, close it and add comment "Implemented in v2.0"
```

### Example 3: Repository Workflow
```bash
Update repository "test-api" to be private and change description to "Internal API"
```

---

# 🐛 Troubleshooting
#### Issue: "GITPASHA__USERNAME not set in .env"
#### Solution: Add your username to `.env`:
```bash
GITPASHA__USERNAME=your_username
```

#### Issue: "Invalid or expired API key"
#### Solution:
1. Verify API key in `.env`
2. Generate new key from https://app.gitpasha.com/settings
3. Ensure no extra spaces in `.env` file

#### Issue: "404 page not found"
#### Solution: Make sure repository name includes username:

- Correct: `"test-repo"` (username added automatically)
- Correct: `"username/test-repo"`

#### Issue: Claude Desktop not connecting
#### Solution:
1. Check `claude_desktop_config.json` syntax
2. Verify file paths use correct slashes
3. Restart Claude Desktop completely
4. Check logs: `logs/gitpasha.log`


#### Issue: SSE connection fails
#### Solution:
1. Verify server is running on `0.0.0.0:8000`
2. Check firewall settings
3. Test with:
    ```bash
    curl http://localhost:8000/sse
    ```

---

# 💬 contact with me:
#### mail: mohamedelawakey@gmail.com
#### whatsapp/phone : +201127247680

---