# gatherings MCP Server

A Model Context Protocol server for managing gatherings and expense sharing.

This is a TypeScript-based MCP server that helps track expenses and payments for social events, making it easy to calculate reimbursements and settle balances between friends.

## Architecture Note

**Important**: This project uses a non-standard architecture for a Node.js application. The TypeScript MCP server acts as a wrapper around a Python backend implementation. The Node.js server receives MCP requests, translates them to command-line calls to the Python script, and returns the results.

While this architecture works for our current needs, it's not the most efficient or maintainable approach for a production application.

### TODO
- Refactor the implementation to use a more standard architecture:
  - Either fully migrate the backend to TypeScript/JavaScript
  - Or implement proper inter-process communication between Node.js and Python components
  - Or replace with a REST API approach where the Python backend provides an API that the MCP server consumes
- Improve error handling between the Node.js and Python components
- Add automated tests for the integration between components
- Optimise Dockerfile 

## Features

### Tools
- `create_gathering` - Create a new gathering
  - Takes `gathering_id` and `members` as required parameters
- `add_expense` - Add an expense for a member
  - Takes `gathering_id`, `member_name`, and `amount` as required parameters
- `calculate_reimbursements` - Calculate reimbursements for a gathering
  - Takes `gathering_id` as a required parameter
- `record_payment` - Record a payment made by a member
  - Takes `gathering_id`, `member_name`, and `amount` as required parameters
- `rename_member` - Rename an unnamed member
  - Takes `gathering_id`, `old_name`, and `new_name` as required parameters
- `show_gathering` - Show details of a gathering
  - Takes `gathering_id` as a required parameter
- `list_gatherings` - List all gatherings
- `close_gathering` - Close a gathering
  - Takes `gathering_id` as a required parameter
- `delete_gathering` - Delete a gathering
  - Takes `gathering_id` as a required parameter, optional `force` parameter
- `add_member` - Add a new member to a gathering
  - Takes `gathering_id` and `member_name` as required parameters
- `remove_member` - Remove a member from a gathering
  - Takes `gathering_id` and `member_name` as required parameters

## Development

Install dependencies:
```bash
npm install
```

Build the server:
```bash
npm run build
```

For development with auto-rebuild:
```bash
npm run watch
```

## Installation

### Configuration

To use with Claude Desktop, add the server config:

```json
{
  "mcpServers": {
    "gatherings": {
      "command": "node",
      "args": ["/path/to/gatherings-server/build/index.js"],
      "env": {
        "GATHERINGS_DB_PATH": "gatherings.db",
        "GATHERINGS_SCRIPT": "/path/to/gatherings-server/gatherings.py"
      },
      "disabled": false,
      "autoApprove": [],
      "alwaysAllow": [
        "create_gathering",
        "add_expense",
        "calculate_reimbursements",
        "record_payment",
        "rename_member", 
        "show_gathering",
        "list_gatherings",
        "close_gathering",
        "delete_gathering",
        "add_member",
        "remove_member"
      ],
      "timeout": 300
    }
  }
}
```

#### Configuration Options

- `command` and `args`: Specifies how to run the server
- `env`: Environment variables
  - `GATHERINGS_DB_PATH`: Path to the database file
  - `GATHERINGS_SCRIPT`: Path to the Python script for handling gathering operations
- `alwaysAllow`: List of tools that will be automatically allowed without prompting
- `timeout`: Maximum execution time in seconds

### Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:

```bash
npm run inspector
```

The Inspector will provide a URL to access debugging tools in your browser.