mcp-ccmonet 0.1.2
ccMonet MCP server for forwarding messages from clients like Claude to ccMonet API
License: MIT
Requires Python: <4.0,>=3.11
Keywords: mcp, claude, ccMonet, ai

# ccMonet MCP Server

This is a server using the Model Context Protocol (MCP) to forward messages from clients like the Claude desktop application to the ccMonet API.

## Quick Start

```bash
# Install the package
pip install mcp-ccmonet

# Configure Claude Desktop (edit claude_desktop_config.json)
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Windows: %AppData%\Claude\claude_desktop_config.json

# Add this configuration:
{
    "mcpServers": {
        "ccMonet": {
            "command": "uvx",
            "args": ["--from", "mcp-ccmonet", "ccMonet"],
            "env": {
                "CCMONET_ORG_ID": "your-org-id",
                "CCMONET_AUTH_TOKEN": "your-auth-token"
            }
        }
    }
}

# Restart Claude Desktop and use the tool!
```

## Features

- Provides an MCP tool `send_message` for sending messages to the ccMonet API and receiving replies
- Supports session management (via thread_id and response_message_id)
- Can be integrated with MCP clients such as the Claude desktop application

## Requirements

- Python 3.11 or higher
- Poetry package manager

## Installation

### Option 1: Install from PyPI (Recommended)

The easiest way to install is directly from PyPI:

```bash
pip install mcp-ccmonet
```

After installation, you can run the server using:

```bash
ccMonet
```

### Option 2: Install from Repository

```bash
# Clone repository
git clone https://github.com/PlatoX-Type/mcp_ccmonet.git
cd mcp_ccmonet

# Install dependencies
poetry install
```

## Usage

### Run Server Directly

#### If installed from PyPI:

```bash
# Run directly using the entry point
ccMonet

# Or using uvx
uvx --from mcp-ccmonet ccMonet
```

#### If installed from repository:

```bash
# From project root
poetry run python mcp_ccmonet/main.py

# Or using the compatibility script
poetry run python run.py
```

### Run with VS Code

The project includes VS Code launch configurations for direct execution:

1. Open the project in VS Code
2. Select "Run MCP Server" (uses the new module structure) or "Run MCP Server (Compatibility)" (uses compatibility script) in the "Run and Debug" panel
3. Click the "Start Debugging" button (F5) to launch

You can also use VS Code tasks:

1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS)
2. Type "Tasks: Run Task" and select it
3. Choose "Run MCP Server" or "Run API Test"

### Integration with Claude Desktop Application

1. Make sure you have the latest version of the Claude desktop application installed
2. Edit the Claude desktop application configuration file:

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

Windows:
```powershell
code $env:AppData\Claude\claude_desktop_config.json
```

3. Add the server configuration:

#### Option 1: Using Local Repository (Development)

```json
{
    "mcpServers": {
        "ccMonet": {
            "command": "poetry",
            "args": [
                "run",
                "python",
                "/absolute/path/to/mcp_ccmonet/main.py"
            ]
        }
    }
}
```

#### Option 2: Using PyPI Package (Recommended for Production)

First install the package from PyPI:
```bash
pip install mcp-ccmonet
```

Then configure Claude Desktop:
```json
{
    "mcpServers": {
        "ccMonet": {
            "command": "uvx",
            "args": ["--from", "mcp-ccmonet", "ccMonet"],
            "env": {
                "CCMONET_ORG_ID": "your-org-id",
                "CCMONET_AUTH_TOKEN": "your-auth-token"
            }
        }
    }
}
```

4. Restart the Claude desktop application
5. Access the ccMonet tool using the MCP tools icon (hammer icon)

## Configuration

The configuration file is located at `mcp_ccmonet/ccmonet_server/config.py`, where you can modify the following settings:

- `API_URL`: The URL of the ccMonet API
- `API_HEADERS`: API request headers, including authentication information
- `SERVER_NAME`: MCP server name
- `REQUEST_TIMEOUT`: API request timeout (seconds)

### Environment Variable Configuration

The server supports configuration of authentication information via environment variables, without modifying the code:

- `CCMONET_ORG_ID`: Organization ID for API authentication
- `CCMONET_AUTH_TOKEN`: Authentication token, without the "Bearer" prefix

Examples:

#### When Using Local Repository

```bash
# Linux/macOS
export CCMONET_ORG_ID="your-org-id"
export CCMONET_AUTH_TOKEN="your-auth-token"
poetry run python mcp_ccmonet/main.py

# Windows PowerShell
$env:CCMONET_ORG_ID="your-org-id"
$env:CCMONET_AUTH_TOKEN="your-auth-token"
poetry run python mcp_ccmonet/main.py
```

#### When Using PyPI Package

After installing the package using `pip install mcp-ccmonet`:

```bash
# Linux/macOS
export CCMONET_ORG_ID="your-org-id"
export CCMONET_AUTH_TOKEN="your-auth-token"
ccMonet

# Windows PowerShell
$env:CCMONET_ORG_ID="your-org-id"
$env:CCMONET_AUTH_TOKEN="your-auth-token"
ccMonet

# Using uvx (alternative)
uvx --from mcp-ccmonet ccMonet
```

When integrating with the Claude desktop application, you can include environment variables in the configuration:

```json
{
    "mcpServers": {
        "ccMonet": {
            "command": "poetry",
            "args": [
                "run",
                "python",
                "/absolute/path/to/mcp_ccmonet/main.py"
            ],
            "env": {
                "CCMONET_ORG_ID": "your-org-id",
                "CCMONET_AUTH_TOKEN": "your-auth-token"
            }
        }
    }
}
```

## Development

### Project Structure

```
mcp_ccmonet/
├── .vscode/             # VS Code configuration
│   ├── launch.json      # Launch configuration
│   ├── settings.json    # Editor settings
│   └── tasks.json       # Tasks configuration
├── mcp_ccmonet/         # Main package directory
│   ├── __init__.py      # Package initialization
│   ├── main.py          # Main entry point
│   └── ccmonet_server/  # Server subpackage
│       ├── __init__.py  # Subpackage initialization
│       ├── config.py    # Configuration file
│       └── server.py    # MCP server implementation
├── docs/
│   └── FAQ.md           # Frequently asked questions
├── tests/               # Test directory
│   └── test_import.py   # Import tests
├── poetry.lock          # Poetry lock file
├── pyproject.toml       # Poetry project configuration
├── README.md            # This file
└── test_api.py          # API test script
```

### Adding New Features

To add new API functionality, create a new tool function in `mcp_ccmonet/ccmonet_server/server.py` and register it using the `@mcp.tool()` decorator.