# JACTUS MCP Server

**Standalone MCP server for [JACTUS](https://github.com/pedronahum/JACTUS)** — Enables AI assistants like Claude Code to directly access JACTUS financial contract simulation capabilities.

## What is this?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a protocol that allows AI assistants to interact with external tools. This package gives Claude (and other MCP-compatible assistants) the ability to discover, validate, and simulate all 18 ACTUS financial contract types powered by [JACTUS](https://github.com/pedronahum/JACTUS).

## Installation

```bash
pip install jactus-mcp
```

This installs the MCP server and pulls `jactus` as a dependency automatically.

### Download Docs & Examples

After installing, optionally download JACTUS documentation and examples from GitHub:

```bash
jactus-mcp setup
```

This downloads the matching version's `docs/` and `examples/` into `~/.jactus-mcp/data/`. You can also specify a tag:

```bash
jactus-mcp setup --tag v0.2.0   # specific version
jactus-mcp setup --force         # re-download
jactus-mcp status                # check what's downloaded
jactus-mcp clean                 # remove downloaded data
```

### From GitHub

```bash
pip install git+https://github.com/pedronahum/JACTUS-MCP.git
```

### For Development

```bash
git clone https://github.com/pedronahum/JACTUS-MCP.git
cd JACTUS-MCP
pip install -e ".[dev]"
```

## Configuration

### Claude Code

Add to your Claude Code MCP settings (`.mcp.json` or settings):

```json
{
  "mcpServers": {
    "jactus": {
      "command": "jactus-mcp"
    }
  }
}
```

Or using Python module:

```json
{
  "mcpServers": {
    "jactus": {
      "command": "python",
      "args": ["-m", "jactus_mcp"]
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "jactus": {
      "command": "jactus-mcp"
    }
  }
}
```

### Transport Options

```bash
# Default: stdio transport (for local clients)
jactus-mcp
# or
python -m jactus_mcp

# Streamable HTTP transport (for remote clients)
python -m jactus_mcp --transport streamable-http
```

## Features

### Core Tools (always available)

These tools work with just `pip install jactus-mcp` — no source tree needed:

| Tool | Description |
|------|-------------|
| `jactus_list_contracts` | List all 18 contract types by category |
| `jactus_get_contract_info` | Get detailed info about a contract type |
| `jactus_get_contract_schema` | Get required/optional parameters for all 18 types |
| `jactus_get_event_types` | List all ACTUS event types |
| `jactus_list_risk_factor_observers` | List all risk factor observer types |
| `jactus_simulate_contract` | **Simulate a contract and get structured cash flows** |
| `jactus_validate_attributes` | Validate contract attributes before simulation |
| `jactus_compute_risk` | Compute DV01, delta, gamma, PV01 risk metrics |
| `jactus_simulate_portfolio` | Simulate a portfolio with aggregation |
| `jactus_get_topic_guide` | Structured guides on 7 topics |
| `jactus_get_quick_start` | Built-in PAM quick start example |
| `jactus_health_check` | Verify installation and JACTUS availability |
| `jactus_get_version_info` | Version information |

### Docs & Example Tools (requires setup)

These tools require JACTUS docs/examples. Enable them with `jactus-mcp setup`:

| Tool | Description |
|------|-------------|
| `jactus_search_docs` | Search across JACTUS documentation |
| `jactus_get_doc_structure` | Browse documentation files and headers |
| `jactus_list_examples` | List Python scripts and notebooks |
| `jactus_get_example` | Retrieve example source code |
| `jactus_run_example` | Execute an example |

Alternatively, point to a local JACTUS checkout:

```bash
export JACTUS_ROOT=/path/to/JACTUS
```

### MCP Resources

| Resource URI | Description |
|--------------|-------------|
| `jactus://docs/architecture` | System architecture guide |
| `jactus://docs/pam` | PAM contract walkthrough |
| `jactus://docs/derivatives` | Derivative contracts guide |
| `jactus://docs/readme` | Project overview |
| `jactus://contract/{type}` | Dynamic contract info + schema |

### MCP Prompts

| Prompt | Description |
|--------|-------------|
| `create_contract` | Guide to create a new contract |
| `troubleshoot_error` | Help troubleshoot errors |
| `understand_contract` | Explain a contract type |
| `compare_contracts` | Compare two contract types |

## Quick Example

With the MCP server running, ask Claude:

> "Simulate a $100k PAM loan at 5% interest maturing in 1 year"

Claude will:
1. Call `jactus_get_contract_schema("PAM")` to get required fields
2. Call `jactus_simulate_contract` with the attributes
3. Return structured cash flow events (IED, IP, MD) with payoff amounts

## Contract Types

JACTUS implements all 18 ACTUS contract types:

- **Principal**: PAM, LAM, LAX, NAM, ANN, CLM
- **Non-Principal**: UMP, CSH, STK
- **Exotic**: COM
- **Derivatives**: FXOUT, OPTNS, FUTUR, SWPPV, SWAPS, CAPFL, CEG, CEC

## Development

### Running Tests

```bash
# Unit tests
pytest tests/ -v --ignore=tests/test_mcp_integration.py

# Integration tests (requires MCP stdio client)
pytest tests/test_mcp_integration.py -v

# All tests
pytest tests/ -v
```

### Architecture

```
JACTUS-MCP/
├── src/jactus_mcp/
│   ├── __init__.py            # Package version
│   ├── __main__.py            # python -m jactus_mcp entry point
│   ├── server.py              # FastMCP server (tools, resources, prompts)
│   ├── models.py              # Pydantic response models
│   └── tools/
│       ├── _utils.py          # Shared utilities (get_jactus_root, type conversion)
│       ├── contracts.py       # Contract discovery & schema (18 types)
│       ├── simulate.py        # Contract simulation
│       ├── examples.py        # Example retrieval & execution
│       ├── validation.py      # Attribute validation
│       ├── documentation.py   # Documentation search & topic guides
│       ├── risk.py            # Risk analytics (DV01, delta, gamma)
│       └── system.py          # Health checks & version info
├── tests/                     # Comprehensive test suite
├── pyproject.toml             # Package configuration
└── README.md
```

## License

Apache License 2.0

## Links

- [JACTUS Library](https://github.com/pedronahum/JACTUS)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Claude Code](https://claude.ai/code)