TicketManagementSystem

# Ticket Management System - MCP/Firebase Integration This project provides an MCP server that integrates Claude for Desktop (MCP client) with Firebase Firestore to implement a ticket management system. ## Feature Overview - Create, update, and add history to tickets - Retrieve ticket list (with filtering and sorting features) - View ticket details - Retrieve master data (users, accounts, categories, etc.) ## System Configuration - **Frontend**: Claude for Desktop (MCP client) - **Backend**: Python MCP Server (Model Context Protocol) - **Database**: Google Cloud Firestore ## Prerequisites - Python 3.10 or higher - firebase-admin - mcp[cli] 1.8.0 or higher - Access permissions to Google Cloud Firestore - Claude for Desktop - uv command-line tool (used in Claude for Desktop settings) ## Environment Setup Steps ### 1. Set Up GCP Project 1. Access [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new GCP project or select an existing project 3. Check that billing is enabled in the "Billing" section and enable it if necessary ### 2. Configure Firestore 1. Enable the Cloud Firestore API ``` Google Cloud Console > APIs & Services > Library > Cloud Firestore API ``` 2. Create a Firestore database - Mode: Select **Native mode** - Location: Choose the database region (e.g., `asia-northeast1` (Tokyo)) - Database ID: `mcp-status-test` (used for this project) 3. Set security rules - Navigate to the "Rules" tab in Firestore - Example development rules (**do not use in production**): ``` rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { match /{document=**} { allow read, write: if true; // Development: Anyone can read and write } } } ``` ### 3. Obtain Service Account and Secret Key 1. Create a service account ``` Google Cloud Console > IAM & Admin > Service Accounts > Create Service Account ``` 2. Assign roles - Select the "Cloud Datastore User" role - Alternatively, assign the "Firestore Data Viewer" and "Firestore Data Editor" roles 3. Download the secret key (JSON) - In the service account's "Keys" tab, click "Create New Key" - Download the JSON key and rename it to `firebase-credentials.json` **Note: Do not include the secret key file in your Git repository.** ### 4. Set Up Local Development Environment 1. Clone the repository ```bash git clone https://github.com/Masa1984a/ticket-management-mcp.git cd ticket-management-mcp ``` 2. Create and activate a Python virtual environment ```bash # Navigate to the project directory cd project_directory_path # Create a Python virtual environment python -m venv .venv # Activate the virtual environment (Windows/PowerShell) .\.venv\Scripts\Activate.ps1 # (For Command Prompt) # .\.venv\Scripts\activate.bat # (For Linux/Mac) # source .venv/bin/activate ``` 3. Place the secret key file - Place the downloaded secret key JSON file in the project root with the name `firebase-credentials.json` 4. Install dependencies ```bash # Upgrade pip to the latest version python -m pip install --upgrade pip # Install dependencies pip install -r requirements.txt ``` 5. Set environment variables Instead of placing the secret key file in the project root, you can set environment variables: ```bash # Windows/PowerShell $env:GOOGLE_APPLICATION_CREDENTIALS = "C:\path\to\your\firebase-credentials.json" # Linux/Mac export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/firebase-credentials.json" ``` 6. Configure Claude for Desktop Edit the Claude for Desktop configuration file `claude_desktop_config.json`: ```json { "mcpServers": { "TicketManagementSystem": { "command": "uv", "args": [ "--directory", "project_directory_path", "run", "main.py" ] } } } ``` **Note**: Replace `project_directory_path` with the actual project path. On Windows, you need to escape backslashes in the path. Example: `C:\\Users\\username\\projects\\ticket-system` ### 5. Prepare Sample Data 1. First, create basic master data: ```bash python ./firestore/firebase_init.py ``` 2. Next, create additional demo data: ```bash python ./firestore/demo_data_generator.py ``` This command will create the following data: - Additional users (e.g., "Shin Ue" as an administrator) - Additional categories (e.g., UX improvement requests) - Chat/LLM reception channels - Approximately 40 demo sample tickets (a balanced combination of categories and statuses) - Sample tickets related to the search functionality 3. Check the inserted data: ```bash python ./firestore/check_firestore_data.py --tickets --search ``` 4. If data creation fails, run the following scripts to troubleshoot: - test_firebase.py: Check connection to Firestore - test_firestore_write.py: Check data creation in Firestore ## How to Run ### Local Testing Run the Python MCP server directly: ```bash python main.py ``` Or use MCP Inspector: ```bash mcp dev main.py ``` - MCP Inspector is an interactive debugging tool for MCP Server developers. It provides a visual interface for developers to test and validate custom tools and servers that integrate with AI applications (Claude for Desktop, Cursor, Roo Code, etc.). ### Registering with Claude for Desktop Register the MCP server with Claude for Desktop: Copy `./claude_desktop_configuration/claude_desktop_configuration.json` to the appropriate folder for Claude for Desktop. After this, launch Claude for Desktop. ## Usage (Claude for Desktop) You can operate the system with natural language commands such as: - "Create a new ticket" - "Show the list of tickets assigned to Yamada" - "Display details of ticket TCK-0001" - "Update the status of ticket TCK-0001 to 'In Progress'" - "Add a comment to ticket TCK-0001" If an index error occurs, please build the index from the URL mentioned in the error message. ## Developer Information ### Project Structure - `main.py`: Implementation of the MCP server - `requirements.txt`: List of dependencies - `README.md`: Project description ### Firestore Schema This system uses the following collections: - `users`: User information (assignees, requesters) - `accounts`: Account information - `categories`: Category information - `categoryDetails`: Category detail information - `statuses`: Status information - `requestChannels`: Reception channel information - `responseCategories`: Response classification information - `tickets`: Ticket information - `counters`: Automatic numbering counters ### MCP Server API This MCP server provides the following tools and resources: **Tools:** - `get_ticket_list`: Retrieve ticket list - `get_ticket_detail`: Retrieve ticket details - `create_ticket`: Create a ticket - `update_ticket`: Update a ticket - `add_ticket_history`: Add history to a ticket - `get_users`: Retrieve user list - `get_accounts`: Retrieve account list - `get_categories`: Retrieve category list - `get_category_details`: Retrieve category details list - `get_statuses`: Retrieve status list - `get_request_channels`: Retrieve reception channel list ## License This project is provided under the MIT License. Please refer to the LICENSE file for details.