Skip to content

README.md

Latest commit

 

History

History
151 lines (118 loc) · 4.31 KB

README.md

File metadata and controls

151 lines (118 loc) · 4.31 KB
Raw

amsc-mcp

FastMCP server exposing the IRI Facility API as MCP tools, designed to connect with LiteLLM.

Features

  • Full coverage of IRI endpoints: Facility, Status, Compute, Filesystem
  • Dynamic OpenAPI spec learning (learn_iri_api) from any live IRI deployment URL
  • Smart elicitation: asks for resource_id, path, or executable when missing
  • Secure Bearer token flow: user provides their IRI token once via elicitation; never stored on disk
  • Async task polling for filesystem operations
  • Three transport modes: HTTP (default), SSE, STDIO

Setup

cd amsc-mcp
uv venv
uv pip install -e .

Environment Variables

Variable Default Description
IRI_BASE_URL https://iri-dev.ppg.es.net/api/v1 IRI Facility API base URL
IRI_MCP_API_KEY (unset = auth disabled) Static key for LiteLLM → MCP auth
MCP_HOST 0.0.0.0 Bind host
MCP_PORT 8006 Bind port
LOG_LEVEL INFO Python logging level

Running the Server

# HTTP (default, for LiteLLM)
IRI_MCP_API_KEY=mysecretkey uv run server.py

# SSE transport
IRI_MCP_API_KEY=mysecretkey uv run server.py --sse

# STDIO (for Claude Desktop / local MCP clients)
uv run server.py --stdio

Connecting with LiteLLM

Add to your LiteLLM config.yaml:

mcp_servers:
  - name: amsc-iri
    url: http://localhost:8006/mcp
    transport: http
    auth:
      type: bearer
      token: "mysecretkey"   # matches IRI_MCP_API_KEY on the server

The server will elicit your personal IRI Bearer token the first time you call any IRI tool. That token is forwarded to the IRI API and held in server memory only — it is never written to disk.

Connecting with Claude Desktop

{
  "mcpServers": {
    "amsc-iri": {
      "command": "uv",
      "args": ["run", "/path/to/amsc-mcp/server.py", "--stdio"],
      "env": {
        "IRI_BASE_URL": "https://your-facility.example.com/api/v1"
      }
    }
  }
}

Tool Reference

Discovery

Tool Description
discover_resources List available resources with IDs, types, status
learn_iri_api(spec_url) Fetch OpenAPI spec from URL → markdown endpoint summary

Facility

Tool Description
get_facility_info Facility name, description, contacts
list_sites List facility sites
get_site(site_id) Details for a specific site

Status

Tool Description
get_resource(resource_id) Resource details and capabilities
list_incidents Active/historical incidents
get_incident(incident_id) Incident details with events
list_events Status change events

Compute

Tool Description
submit_job Submit a job (elicits resource_id and executable if missing)
get_job_status(resource_id, job_id) Job state, timing, exit code
list_jobs All jobs on a resource
cancel_job(resource_id, job_id) Cancel a job

Filesystem (all ops poll async tasks automatically)

Tool Description
ls List directory
stat File metadata
file_type File type
head / tail / view Read file content
checksum SHA-256 checksum
mkdir / rm Create / delete
cp / mv / symlink Copy / move / link
chmod / chown Permissions
download / upload Transfer files
compress / extract Archive operations

Auth

Tool Description
clear_iri_token Remove cached IRI token (re-elicits on next call)
refresh_api_cache Clear OpenAPI spec cache

Example Session

User: Show me what compute resources are available

→ discover_resources(resource_type="compute")
  Returns table: nersc-perlmutter | compute | ✅ ok | ...

User: Submit a quick test job on perlmutter that runs hostname

→ submit_job(resource_id="nersc-perlmutter", executable="/bin/hostname",
             job_name="test", walltime_minutes=5)
  Returns: job_id = "12345678"

User: Check if it's done

→ get_job_status(resource_id="nersc-perlmutter", job_id="12345678")
  Returns: ✅ COMPLETED, exit code 0

User: Download the output file

→ download(resource_id="nersc-perlmutter-fs", path="/scratch/user/hostname.out")
  Returns: file content as text