# MREF Contract Manager — MCP Server

> **IBM Maximo Real Estate and Facilities · AI-powered contract management via Model Context Protocol**

[![Status](https://img.shields.io/badge/status-production--ready-brightgreen)](.)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](.)
[![Tests](https://img.shields.io/badge/tests-10%20pass%20%C2%B7%200%20fail-brightgreen)](docs/DEMO.txt)
[![Protocol](https://img.shields.io/badge/protocol-MCP%20%2F%20OSLC-orange)](.)

---

## Demo

![All 11 operations running live](docs/demo.svg)

> Animated SVG — plays automatically. Full console output: [docs/DEMO.txt](docs/DEMO.txt)

---

## What it does

The **MREF Contract Manager MCP Server** connects IBM Bob (AI assistant) to a live IBM Maximo Real Estate and Facilities instance through OSLC REST APIs, exposing **10 tools** for natural-language contract management — no manual API calls required.

```
"Show me all active leases expiring this year"
"Create a 5-year lease for the Chicago office starting 2026-01-01"
"Export all contracts to CSV"
"Search contracts containing termination option"
"Bulk import from contracts_q1.csv"
"Generate an executive portfolio report"
```

---

## Architecture

```
┌──────────────────────────────────────────┐
│           IBM Bob (AI Assistant)         │
│           MCP Client Layer               │
└──────────────────┬───────────────────────┘
                   │  Model Context Protocol (stdio)
┌──────────────────▼───────────────────────┐
│    mref_comprehensive_mcp_server.py      │
│          FastMCP Server · 10 Tools       │
└──────────────────┬───────────────────────┘
                   │  HTTP/HTTPS · OSLC REST
┌──────────────────▼───────────────────────┐
│          mref_oslc_client.py             │
│    MREFOSLCClient · Session management   │
└──────────────────┬───────────────────────┘
                   │  JSESSIONID cookie auth
┌──────────────────▼───────────────────────┐
│  IBM Maximo Real Estate and Facilities   │
│  /p/websignon/signon                     │
│  /oslc/spq/cstRELeaseQC  (GET)           │
│  /oslc/so/cstRELeaseCF   (POST)          │
└──────────────────────────────────────────┘
```

---

## The 10 Tools

| # | Tool | What it does |
|---|------|-------------|
| 1 | `verify_connection` | Tests authentication and API reachability |
| 2 | `fetch_all_contracts` | Retrieves all contracts with pagination |
| 3 | `fetch_contracts_filtered` | Filters by status, city, country, date range |
| 4 | `search_contracts_by_name` | Full-text name search across all records |
| 5 | `get_contract_statistics` | Status / location / date breakdowns |
| 6 | `generate_comprehensive_report` | Markdown or JSON report (summary / detailed / executive) |
| 7 | `create_contract` | Creates a new contract via OSLC POST |
| 8 | `update_contract` | *(roadmap — PUT not yet implemented)* |
| 9 | `export_contracts_csv` | Exports records to a local CSV file |
| 10 | `bulk_import_contracts` | Batch-creates contracts from a CSV file |

---

## Quick Start

### 1 · Prerequisites

| Requirement | Version |
|-------------|---------|
| Python | **3.11+** |
| IBM Bob | MCP-enabled build |
| MREF access | Valid username + password |

### 2 · Install

```bash
git clone https://github.com/rjbhavar/MREF-Contract-Management-MCP
cd MREF-Contract-Management-MCP
python3.11 -m pip install -r requirements.txt
```

### 3 · Configure

```bash
cp config.example.json config.json
# edit config.json → set base_url, username, password
```

`config.json` is gitignored and never committed.

### 4 · Register with IBM Bob

Add to your workspace `.bob/mcp.json`:

```json
{
  "mcpServers": {
    "mref-contract-manager": {
      "command": "python3.11",
      "args": ["-u", "/absolute/path/to/mref_comprehensive_mcp_server.py"],
      "cwd": "/absolute/path/to/MREF-Contract-Management-MCP"
    }
  }
}
```

### 5 · Verify

```bash
python3.11 test_all_operations.py
```

Expected: `Result: 10 passed · 0 failed · 1 skipped  (of 11 total)`

---

## Repository Structure

```
MREF-Contract-Management-MCP/
├── mref_comprehensive_mcp_server.py   # FastMCP server — 10 tools
├── mref_oslc_client.py                # OSLC API client
├── test_all_operations.py             # End-to-end test suite
├── config.example.json                # Configuration template
├── requirements.txt
├── oslc-objects/                      # OSLC package — import into your instance
│   ├── MREF_Contract_OSLC_v2.zip
│   ├── cstRELeaseCF.json
│   ├── cstRELeaseQC.json
│   └── manifest.json
└── docs/
    ├── demo.svg                       # Animated terminal demo (this README)
    └── DEMO.txt                       # Full console output
```

---

## OSLC API Reference

**Auth**
```
POST /p/websignon/signon
{ "userName": "<user>", "password": "<pass>" }
→ sets JSESSIONID cookie
```

**Query**
```
GET /oslc/spq/cstRELeaseQC?oslc.select=*&oslc.pageSize=100
```

**Create**
```
POST /oslc/so/cstRELeaseCF
{ "userName": "<user>", "password": "<pass>",
  "spi:triNameTX": "My Lease", "spi:triIdTX": "LEASE-001", ... }
```

**Key fields:** `dcterms:identifier` · `spi:triNameTX` · `spi:triIdTX` · `spi:triCityTX` · `spi:triStateProvTX` · `spi:triCountryTX` · `spi:triStartDA` · `spi:triExpirationDA` · `spi:triContractStatusCL` · `spi:triProviderTypeLI`

---

## Object Migration

The OSLC package is bundled — no export step needed.

1. Download [`oslc-objects/MREF_Contract_OSLC_v2.zip`](oslc-objects/MREF_Contract_OSLC_v2.zip)
2. Log in to MREF → **Tools → Administration → Object Migration → New Import Package**
3. Upload the `.zip`, click **Validate**, then **Import**
4. Run `python3.11 test_all_operations.py` to confirm

Full guide: [OBJECT_MIGRATION_GUIDE.md](OBJECT_MIGRATION_GUIDE.md)

---

## Security

- Credentials stored in `config.json` (gitignored, never committed)
- All POST payloads use `client.username` / `client.password` from the loaded config — no hardcoded values anywhere
- JSESSIONID held in memory only for session lifetime
- SSL cert verification configurable in `mref_oslc_client.py`

---

## Troubleshooting

| Symptom | Resolution |
|---------|-----------|
| `Authentication failed: HTTP 404` | `base_url` must not include `/app/tririga` |
| `ModuleNotFoundError: fastmcp` | `python3.11 -m pip install -r requirements.txt` |
| Tool not visible in Bob | Restart Bob; verify `mcp.json` path is absolute |
| No contracts returned | Run `verify_connection` first |

---

## License

Apache 2.0 — see [LICENSE](LICENSE)

---

**Version:** 2.3.0 · **Status:** ✅ Production Ready  
*Made with IBM Bob*