From 65be013fcfd05d50e468484efe5b5cb5bd9ec757 Mon Sep 17 00:00:00 2001 From: MohamedAlawakey Date: Sat, 22 Nov 2025 18:12:30 +0200 Subject: [PATCH] GitPasha MCP Server - Ready for deployment --- .env.example | 2 +- README.md | 560 +++++++++++++++++++++++++++++++++++++--------- helpers/logger.py | 15 +- 3 files changed, 464 insertions(+), 113 deletions(-) diff --git a/.env.example b/.env.example index e3352ce..cbc9a13 100644 --- a/.env.example +++ b/.env.example @@ -3,7 +3,7 @@ GITPASHA_API_KEY='your_api_key' GITPASHA_BASE_URL=https://app.gitpasha.com/api/v1 GITPASHA__USERNAME='your_user_name' -LOG_LEVEL=DEBUG +LOG_LEVEL=INFO # ← Options: INFO, WARNING, ERROR (DEBUG for development only) LOG_FILE=logs/gitpasha.log MCP_TRANSPORT=sse diff --git a/README.md b/README.md index 27eb51a..5af5886 100644 --- a/README.md +++ b/README.md @@ -1,161 +1,501 @@ -# Git Pasha MCP Server +# 🎯 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 -Simple MCP server for managing Git Pasha repositories. +--- -## File Structure +# ✨ 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 -β”œβ”€β”€ requirements.txt -β”œβ”€β”€ .env -β”œβ”€β”€ .env.example -β”œβ”€β”€ .gitignore -β”œβ”€β”€ README.md -β”œβ”€β”€ helpers/ +β”œβ”€β”€ πŸ“„ 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 -β”‚ β”œβ”€β”€ headers.py -β”‚ β”œβ”€β”€ descriptions.py -β”‚ β”œβ”€β”€ error_formatter.py -β”‚ β”œβ”€β”€ logger.py -β”‚ └── http_client.py -β”œβ”€β”€ api/ -β”‚ β”œβ”€β”€ __init__.py -β”‚ β”œβ”€β”€ repos/ +β”‚ β”œβ”€β”€ πŸ“‚ repos/ # Repository operations β”‚ β”‚ β”œβ”€β”€ __init__.py -β”‚ β”‚ β”œβ”€β”€ create.py -β”‚ β”‚ β”œβ”€β”€ update.py -β”‚ β”‚ └── delete.py -β”‚ β”œβ”€β”€ issues/ +β”‚ β”‚ β”œβ”€β”€ create.py # Create repository +β”‚ β”‚ β”œβ”€β”€ update.py # Update repository +β”‚ β”‚ └── delete.py # Delete repository +β”‚ β”œβ”€β”€ πŸ“‚ issues/ # Issue operations β”‚ β”‚ β”œβ”€β”€ __init__.py -β”‚ β”‚ β”œβ”€β”€ list.py -β”‚ β”‚ β”œβ”€β”€ create.py -β”‚ β”‚ └── update.py -β”‚ β”œβ”€β”€ files/ +β”‚ β”‚ β”œβ”€β”€ list.py # List issues +β”‚ β”‚ β”œβ”€β”€ create.py # Create issue +β”‚ β”‚ └── update.py # Update issue +β”‚ β”œβ”€β”€ πŸ“‚ pulls/ # Pull request operations β”‚ β”‚ β”œβ”€β”€ __init__.py -β”‚ β”‚ └── create_readme.py -β”‚ └── pulls/ +β”‚ β”‚ └── open.py # Open pull request +β”‚ └── πŸ“‚ files/ # File operations β”‚ β”œβ”€β”€ __init__.py -β”‚ └── open.py -└── tools/ - β”œβ”€β”€ __init__.py - β”œβ”€β”€ repo_create.py - β”œβ”€β”€ repo_update.py - β”œβ”€β”€ repo_delete.py - β”œβ”€β”€ issue_create.py - β”œβ”€β”€ issue_list.py - β”œβ”€β”€ issue_update.py - └── pr_open.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 ``` -## Features +--- -- βœ… Create new repositories (with auto-suggested descriptions) -- βœ… Delete existing repositories -- βœ… Edit repository details -- βœ… List all repositories -- βœ… Get description suggestions +# πŸ”§ Installation +### Prerequisites: +- Python 3.12+ installed +- Git installed +- GitPasha account with API access +- Docker (optional, for cloud deployment) -## Setup +##### Step 1: Clone the Repository +```bash +git clone https://github.com/YOUR_USERNAME/gitpasha-mcp.git +cd gitpasha-mcp +``` -### 1. Install Dependencies +##### 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 ``` -### 2. Setup API Key - -Copy `.env.example` to `.env` and add your Git Pasha API key: +--- +# βš™οΈ Configuration +##### Step 1: Create Environment File ```bash +# Copy the example file cp .env.example .env ``` -Edit `.env` and add your key: -``` -GITPASHA_API_KEY=your_actual_key_here -``` - -Get your API key from: https://app.gitpasha.com/settings - -### 3. Run Locally - +##### Step 2: Configure `.env` +**Edit `.env` with your credentials:** ```bash -python server.py +# 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 ``` -### 4. Add to Claude Desktop +##### 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 -Edit Claude config file: -**Mac/Linux:** `~/Library/Application Support/Claude/claude_desktop_config.json` +##### Step 4: Create Logs Directory +```bash +mkdir logs +``` -**Windows:** `%APPDATA%\Claude\claude_desktop_config.json` +--- -Add this: +# πŸš€ 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 { - "mcpServers": { - "gitpasha": { - "command": "python", - "args": ["C:\\Users\\Yours\\Desktop\\MCP Server\\git basha\\server.py"] - } - } + "name": "test-repo", + "description": "Test repository from inspector", + "private": false } ``` -#### > πŸ“ **Important Note** -Make sure to go to the following path: +###### List Issues: +```json +{ + "repo": "test-repo", + "state": "open" +} +``` + +--- + +# πŸ–₯️ Claude Desktop Integration + +##### Step 1: Locate Config File + +**Windows:** ```bash -C:\Users\Alawakey\AppData\Local\AnthropicClaude\app-0.13.64\logs\gitpasha.log +%APPDATA%\Claude\claude_desktop_config.json ``` -- If you find the file `logs\gitpasha.log` βœ… β€” everything is fine, and the server can run properly. -- If the file **doesn’t exist** ❌ β€” you need to **create it manually** so the server can start correctly. - - -## Usage Examples - -### Create Repository -``` -Create a new repo called "my-awesome-api" -``` -Auto-suggests: "RESTful API service" - -### Edit Repository -``` -Edit repo "old-name" to have description "New description" +**macOS:** +```bash +~/Library/Application Support/Claude/claude_desktop_config.json ``` -### Delete Repository -``` -Delete repo "test-repo" with confirmation +**Linux:** +```bash +~/.config/Claude/claude_desktop_config.json ``` -### List Repositories -``` -Show me all my repositories +##### 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" + } + } + } +} ``` -## Tools Available +**For Cloud/Remote (SSE):** +```json +{ + "mcpServers": { + "gitpasha": { + "url": "https://your-app.ghaymah.systems/sse", + "transport": "sse" + } + } +} +``` -1. **create_repo** - Create new repository -2. **delete_repo** - Delete repository (requires confirmation) -3. **edit_repo** - Update repository settings -4. **list_repos** - List all repositories -5. **get_description_suggestion** - Get description idea for repo name +##### Step 3: Restart Claude Desktop +**Close and reopen Claude Desktop completely.** -## Notes +##### Step 4: Verify Connection +**In Claude Desktop, look for the πŸ”Œ hammer icon indicating MCP servers are connected. You should see `"gitpasha"` listed.** -- All descriptions are auto-suggested in English -- Simple and clean code -- Works locally and with Claude Desktop -- Requires Git Pasha API key +--- -# create repo --> enter the repo name + description -# delete repo --> enter the user name / name repo. EX: (mohamedelawakey/testat) -# update repo --> enter the repo like steps of delete the enter the new name if you want then description if also you want, then chose if you want the repo private or no +# ☁️ Deployment +### Docker Deployment +**Build Image** +```bash +docker build -t gitpasha-mcp:latest . +``` -# to update the issues enter the (mohamedelawakey/testat) as a repo, issue as a number of these issue, title, and all as you want +```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 + +--- diff --git a/helpers/logger.py b/helpers/logger.py index 448a8b1..537dbd2 100644 --- a/helpers/logger.py +++ b/helpers/logger.py @@ -1,11 +1,21 @@ import os import logging -LOG_LEVEL = os.getenv("LOG_LEVEL", "DEBUG").upper() +LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper() LOG_FILE = os.getenv("LOG_FILE", "logs/gitpasha.log") +ALLOWED_LEVELS = { + "INFO": logging.INFO, + "WARNING": logging.WARNING, + "ERROR": logging.ERROR, + "CRITICAL": logging.CRITICAL, + "DEBUG": logging.DEBUG +} + +log_level = ALLOWED_LEVELS.get(LOG_LEVEL, logging.INFO) + logging.basicConfig( - level=getattr(logging, LOG_LEVEL, logging.DEBUG), + level=log_level, format="%(asctime)s | %(levelname)s | %(message)s", handlers=[ logging.FileHandler(LOG_FILE, mode="a", encoding="utf-8"), @@ -14,3 +24,4 @@ logging.basicConfig( ) log = logging.getLogger("gitpasha") +log.info(f"Logger initialized with level: {LOG_LEVEL}")