Jama MCP Server

🚀 Simplified Chinese Connection Guide

This guide provides a detailed introduction to the project configuration, operation, and troubleshooting of the Simplified Chinese connection project. It helps users quickly get started with the project and solve potential problems.

🚀 Quick Start

Project Configuration and Operation

Project Structure

1. Project Files:

   • jama_mcp_server/server.py: The main service module responsible for handling operations related to Jama Connect.
   • test_mcp_client.py: A test client script for direct debugging by calling server tools.

2. Runtime Environment:

   • Ensure that the necessary dependencies (such as Python and uv) are installed.
   • Configure the environment variables required for the project.

Service Operation

Direct Operation

Execute the following command in the terminal to start the service:

# Switch to the jama-mcp-server directory
uv run python -m jama_mcp_server.server

Docker Configuration

When running the service using Docker, you can refer to the following JSON configuration example (mcp_settings.json):

{
  "mcpServers": {
    "jama-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "JAMA_URL", "-e", "JAMA_CLIENT_ID", "-e", "JAMA_CLIENT_SECRET", "-e", "JAMA_MOCK_MODE",
        "jama-mcp-server"
      ],
      "env": {
        "JAMA_URL": "https://your-jama-instance.com",
        "JAMA_CLIENT_ID": "your-client-id",
        "JAMA_CLIENT_SECRET": ""
      }
    }
  }
}

Environment Variable Configuration

Required Environment Variables

• JAMA_URL: The URL address of the Jama Connect instance.
• JAMA_CLIENT_ID and JAMA_CLIENT_SECRET: Client ID and secret key for authentication.

Optional Environment Variables

• JAMA_AWS_SECRET_PATH: Specify the secret path if using AWS parameter storage.
• JAMA_AWS_PROFILE: Specify the name of the AWS configuration file to use.
• JAMA_MOCK_MODE: Set to true to enable mock mode (disabled by default).

Service Startup Example

An example JSON configuration when running the service using the uv command:

{
  "mcpServers": {
    "jama-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "jama_mcp_server.server"
      ],
      "cwd": "/path/to/your/clone/jama-mcp-server",
      "env": {
        "JAMA_URL": "https://your.jama.instance.com",
        "JAMA_CLIENT_ID": "your_client_id",
        "JAMA_CLIENT_SECRET": "your_client_secret",
        "JAMA_AWS_SECRET_PATH": "/path/to/your/jama/secret",
        "JAMA_AWS_PROFILE": "your-aws-profile-name",
        "JAMA_MOCK_MODE": "false"
      }
    }
  }
}

💻 Usage Examples

Using the Test Script

Run the test client:

# Switch to the jama-mcp-server directory
uv run python test_mcp_client.py

This script starts the server and calls predefined tools for testing, including successful and expected failure cases. It also provides a summary after outputting the results.

Available Tools

This service provides a variety of read-only tools. For specific functions, please refer to the MCP client interface or relevant documentation.

🔧 Troubleshooting

Common Problems

1. Environment Variables Not Configured:

   • Check if JAMA_URL, JAMA_CLIENT_ID, and JAMA_CLIENT_SECRET are correctly set.

2. Docker Run Failure:

   • Ensure that the Docker service is installed and enabled.
   • Check if you have sufficient permissions to run containers.

3. Mock Mode Not Working:

   • Confirm whether JAMA_MOCK_MODE is set to true.

Solutions

1. Verify Environment Variables:

echo $JAMA_URL
echo $JAMA_CLIENT_ID
echo $JAMA_CLIENT_SECRET

2. Check Log Output:

   • View the detailed logs when the service starts to confirm if there are any error messages.

3. Reconfigure Environment Variables:

export JAMA_MOCK_MODE=true
uv run python -m jama_mcp_server.server

📄 License

The use and distribution of this project must comply with the terms of the Project License.

If you have any questions or suggestions, please contact the maintenance team.