# HRSSC / ELM Reference MCP Server

An MCP server exposing two independently queryable, fully offline vector
databases for USPS/APWU labor-relations research:

- **`query_elm`** — the USPS Employee and Labor Relations Manual (ELM),
  chunked by its own section numbering (e.g. `511.43`, `665.41`).
- **`query_hrssc`** — the 2024-2029 APWU-HRSSC National Agreement,
  chunked by Article/Section, with source page numbers.

Both are semantic-search (embedding-based) retrieval tools. They surface
the relevant text with exact citations; they do not interpret whether a
provision applies to any specific situation — always verify the returned
text against the actual document before relying on it.

## What's in here

```
data/
  ELM_vectordb/      Chroma DB, collection "elm"
  HRSSC_vectordb/     Chroma DB, collection "hrssc_agreement"
src/
  server.py           MCP server (FastMCP), two tools
requirements.txt
```

Source material: ELM downloaded from the official USPS site
(about.usps.com/manuals/elm/), March 2024 edition. HRSSC Agreement
digitized from a personal printed copy (OCR'd, so expect occasional OCR
noise in exact wording -- always confirm against the actual contract
for anything consequential).

## Setup

```bash
pip install -r requirements.txt
```

## Using with Claude Code / Claude Desktop

Add to your MCP config (e.g. `claude_desktop_config.json` or
`.claude/mcp.json`):

```json
{
  "mcpServers": {
    "hrssc-elm-reference": {
      "command": "python",
      "args": ["/absolute/path/to/hrssc-elm-mcp/src/server.py"]
    }
  }
}
```

Then ask Claude things like "check the ELM for reasonable accommodation
standards" or "what does the HRSSC agreement say about non-career
employees" and it will call `query_elm` / `query_hrssc` directly.

## Using with ChatGPT / GPT-side tooling

ChatGPT doesn't speak MCP natively. Two practical options:

1. **Local script, not a live connector**: run `src/server.py`'s
   underlying `chromadb` queries directly in a Python environment (e.g.
   a Code Interpreter session with the `data/` folder uploaded) --
   see the `query_elm` / `query_hrssc` functions in `server.py` for the
   exact query pattern to copy.
2. **Wrap it as an HTTP API** (not included here) and expose it as a
   Custom GPT Action, if you want live access from a hosted GPT rather
   than a one-off Code Interpreter session.

## Standalone query script

For a quick terminal lookup without going through MCP at all:

```bash
python -c "
import sys
sys.path.insert(0, 'src')
from server import query_elm, query_hrssc
print(query_elm('your question here'))
print(query_hrssc('your question here'))
"
```

## Caveats

- Retrieval only, not legal advice. Verify citations against the actual
  documents before relying on them for anything consequential.
- HRSSC Agreement text went through OCR on phone-photographed pages;
  spot-check exact wording on anything that matters.
- Neither DB covers the main APWU-USPS National Agreement (a separate
  document from the HRSSC-specific agreement) or USPS Handbook EL-307
  (Reasonable Accommodation procedures) -- not included here.