JACTUS MCP Server

Standalone MCP server for JACTUS — Enables AI assistants like Claude Code to directly access JACTUS financial contract simulation capabilities.

What is this?

Model Context Protocol (MCP) 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.

Installation

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:

jactus-mcp setup

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

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

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

For Development

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):

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

Or using Python module:

{
  "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

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

Transport Options

# 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:

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

# 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
• Model Context Protocol
• Claude Code