# TPLCP Reference MCP

This local MCP server turns the 2026 CLCP orientation corpus into a searchable,
citation-preserving reference source for TPLCP report work. It keeps source files
local, preserves relative paths and SHA-256 identifiers, prioritizes current
internal standards, and excludes credential-oriented files from search by default.

## Data flow

1. Run `tools/corpus_extract.py` against the orientation folder. The extractor
   inventories every file, hashes exact duplicates, and writes `files.jsonl` plus
   readable text under `texts/`.
2. Run `build_index.py` to create `tplcp_reference.sqlite3` in that extraction
   directory.
3. Set `TPLCP_INDEX_DIR` to the extraction directory and run `server.py` over MCP
   stdio.

The checked-in server is intentionally separate from the source corpus. Do not
commit the extracted text cache or any source documents containing client records,
credentials, or personal information.

## Tools

- `tplcp_retrieve_for_question`: preferred first step for a natural-language question. Returns a ranked evidence pack with controlling guidance first, examples second, and contextual references third.
- `tplcp_search_reference`: paged full-text search with role/module filters and source provenance.
- `tplcp_get_reference_document`: bounded, path- or SHA-256-addressed excerpts.
- `tplcp_get_standards`: highest-authority current TPLCP standards for a topic.
- `tplcp_get_report_examples`: illustrative report/template patterns.
- `tplcp_list_modules`: orientation module map.
- `tplcp_reindex_reference`: explicit local cache rebuild after a new extraction.

## Skill suite

The `skills/` directory contains the 15 operational TPLCP skills defined by the
reporting playbook:

1. `tplcp-reporting-orchestrator`
2. `tplcp-medical-review-summary`
3. `tplcp-life-care-plan`
4. `tplcp-medical-cost-projection`
5. `tplcp-report-writing-standards`
6. `tplcp-executive-summary`
7. `tplcp-clinical-recommendation-research`
8. `tplcp-standardized-assessment-interview`
9. `tplcp-coding-costing-methodology`
10. `tplcp-vendor-survey-atus`
11. `tplcp-life-expectancy`
12. `tplcp-rebuttal-analysis`
13. `tplcp-deposition-trial-prep`
14. `tplcp-report-qa`
15. `tplcp-privacy-source-control`

Each skill has a required `SKILL.md` and UI metadata under `agents/openai.yaml`.
The skills retrieve current guidance through the MCP and do not contain the
private orientation corpus.

To install the skills into a local Codex skills directory:

```bash
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/* "${CODEX_HOME:-$HOME/.codex}/skills/"
```

After installation, connect the MCP server, then invoke the orchestrator or a
specialized skill by name. Keep the local corpus extraction and SQLite index
outside the repository.

## Question behavior

For a natural-language question, use `tplcp_retrieve_for_question` first. The
tool makes the source hierarchy explicit:

1. Current internal TPLCP standards, workflow guidance, templates, and
   orientation instructions are the controlling source of truth.
2. TPLCP and external report examples show structure and patterns but do not
   override current guidance.
3. Clinical, costing, testimony, and educational materials provide context and
   require professional judgment.

The calling model should answer from the returned excerpts, preserve source
paths and page numbers as citations, and identify when the corpus does not
contain enough information to answer confidently. The tool retrieves evidence;
it does not make medical, legal, or case-specific conclusions.

## Example MCP configuration

```json
{
  "mcpServers": {
    "tplcp-reference": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/tplcp_reference_mcp/server.py"],
      "env": {
        "TPLCP_INDEX_DIR": "/absolute/path/to/analysis/clcp_corpus"
      }
    }
  }
}
```

Use `TPLCP_INDEX_DB` instead when the SQLite file is stored separately.

## Local MCP client connection

The current server works locally over stdio. Configure a local MCP-capable
client with:

```json
{
  "mcpServers": {
    "tplcp-reference": {
      "command": "/absolute/path/to/python",
      "args": ["/absolute/path/to/tplcp-reference-mcp/server.py"],
      "env": {
        "TPLCP_INDEX_DIR": "/absolute/path/to/clcp_corpus"
      }
    }
  }
}
```

## ChatGPT or hosted GPT connection

Hosted ChatGPT cannot reach a process listening only on this Mac. It needs an
HTTPS MCP endpoint. The recommended path for this private source of truth is
OpenAI's Secure MCP Tunnel:

```bash
tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile tplcp-reference \
  --tunnel-id <tunnel_id> \
  --mcp-command "env TPLCP_INDEX_DIR='/absolute/path/to/clcp_corpus' '/absolute/path/to/python' '/absolute/path/to/tplcp-reference-mcp/server.py'"

tunnel-client doctor --profile tplcp-reference --explain
tunnel-client run --profile tplcp-reference
```

Then create a developer-mode app in ChatGPT, choose **Tunnel**, select the
tunnel, scan the tools, and test it in a new chat. Keep the app read-only by
allowlisting the retrieval, standards, examples, document, and module tools.
Do not expose this corpus through an unauthenticated public URL.

For a directly hosted deployment, run `server.py --transport
streamable-http` and expose only the authenticated HTTPS `/mcp` endpoint. The
server supports this transport, but the private tunnel is safer for source
material containing company standards and case-related references.