• Arguments: table_name (required); schema_name (optional — if empty the workflow asks you to pick a schema, defaulting to SQLUser).
• What it does: drives res_tables_all (when the schema is unknown), describe_table for columns and types, fetch_data for a small sample (first five rows), and finally writes a recommendation for indexes that would help typical access patterns.

• Arguments: query = full class name (for example MCPTest.BP.QueryService).
• What it does: calls get_class_source, then summarizes InstanceMethods / ClassMethods, properties, and — when present — the <Storage> block and related globals.
• Use it when: you need a readable overview before editing or documenting code. Several other prompts chain into explore-class for deeper analysis.

• Arguments: table_name; a csv_sample string (headers plus a few rows are enough); optional table_schema.
• What it does: infers types from the sample, checks whether the target already exists via res_tables_all, refuses to overwrite blindly, then calls import_csv_to_iris. After load it uses describe_table and fetch_data (for example SELECT COUNT(*)) to verify shape and row counts, and may suggest create_index once you agree on names.
• Try it with the bundled sample: paste the first few lines of https://github.com/pietrodileo/iris-mcp-blueprint/blob/main/example_data/patients.csv (header + a handful of rows) into csv_sample, set table_name to a fresh name such as Patients, and optionally table_schema to MCPTest (or any schema you like). The workflow will create the table and load all rows.

• Arguments: table_name (required); format = json (default), csv, or txt; optional table_schema (the workflow asks if empty, defaulting to SQLUser).
• What it does:
  1. Resolves the schema (via res_tables_all / get_tables if table_schema is empty).
  2. Calls describe_table to show the user the columns and types that will be exported.
  3. Runs SELECT COUNT(*) via fetch_data and warns if the table is large (>~10 000 rows).
  4. Asks the user whether to export everything (limit=0), apply a WHERE filter, restrict to a subset of columns, or keep the default limit=1000.
  5. Calls the export_table tool with the agreed scope and chosen format.
  6. Previews the first few lines/items and reports the total length, then explains how to save the output (e.g. <table_name>.<format>).
• Tool details (export_table):
  • format — 'json' returns a list of objects (null for SQL NULL, Decimal and datetime serialized as strings); 'csv' follows RFC 4180 with a comma delimiter and CRLF line terminator; 'txt' reuses the pipe-separated table layout shared with the other SQL tools.
  • columns — optional list of column names. Each is validated as a SQL identifier ([A-Za-z_][A-Za-z0-9_]*) before being inlined.
  • where — optional SQL fragment without the leading WHERE keyword (e.g. Age > 30 AND City = 'Rome'). Caller is responsible for escaping; for untrusted input use fetch_data with parameters instead.
  • limit — defaults to 1000. Pass 0 (or a negative value) to disable the cap. Implemented as IRIS SELECT TOP N, so it streams only the requested rows.
• Try it with the demo data: after MCPTest.Employer.PopulateAndAssign() has run (auto-seeded by iris.script on first start, or invoked via run_class_method), call the prompt with table_name: Employer, table_schema: MCPTest, format: json (or csv / txt).

• Arguments: query = any text to find in class sources (API name, method name, ObjectScript fragment).
• Steps: search_code → list of matching classes → you choose which hits matter → those classes are studied further (the prompt text tells the model to reuse explore-class) → short explanation of how the string appears in each chosen class.
• Use it for: refactors, security reviews, or learning how a pattern is used in your application.

• Arguments: table_name; optional table_schema. The class is treated as {table_schema}.{table_name} when that matches your persistent package.
• What it does: locates every distinct global and explains its role (data vs index vs stream) and may call check_global / check_global_content or fetch_data to verify their content.
• Use it when: you care about physical layout, not only column names.

• Arguments: bp_class (for example MCPTest.BP.QueryService); optional bp_config_name, bs_config_name, web_app_path, production_name.
• What it does:
  1. Verifies OnRequest / EnsLib.HTTP.GenericMessage on the BP.
  2. Ensures an active production exists.
  3. Calls add_production_item for the BP and for the REST BS (with TargetConfigNames).
  4. Calls register_web_application, then update_production, with optional list_production_items.
  5. For MCPTest.BP.QueryService, runs MCPTest.Employer:PopulateAndAssign via run_class_method to seed demo data.
  6. Applies the BS setting tweaks listed in the prompt.
  7. Documents the URL pattern http://<host>:<webport><web_app_path>/<bs_config_name> and runs an HTTP smoke test.
• After running it: validate with the curl examples in How to test them (Cursor and similar clients).

1. Start IRIS (docker compose up -d) and configure the MCP server using Environment variables (IRIS connection) and the JSON example under Option A — Local later in this README so the client can reach IRIS (IRIS_PORT, IRIS_NAMESPACE, credentials, etc.).
2. In the client, open the MCP prompts UI for iris-mcp-blueprint (wording varies: “Prompts”, slash command, or the model picker’s MCP prompt list).
3. Select a prompt by name (e.g. explore-class) and pass the parameters the prompt expects (e.g. class name MCPTest.BP.QueryService).
4. Send the message and confirm the assistant follows the steps: it should call the listed tools and report results. If a step returns ERROR:, fix IRIS connectivity or inputs and retry.

Example inputs and full QueryService test (after IRIS is up and MCP is configured):

• explore-class — query: MCPTest.Employer or MCPTest.BP.QueryService.

• analyze-table — table_name: Employer, schema_name: MCPTest (or your SQL schema; leave empty to exercise schema discovery).

• search-for-code — query: PopulateAndAssign or EnsLib.REST.GenericService.

• analyze-table-globals-content — same table/schema as analyze-table, for example Employer / MCPTest.

• import-csv-workflow — paste the first few lines of https://github.com/pietrodileo/iris-mcp-blueprint/blob/main/example_data/patients.csv into csv_sample, with table_name: Patients and an unused schema such as MCPTest. (You can also use any small fictional CSV and a new table_name that does not already exist.)

• export-table — table_name: Employer, table_schema: MCPTest, format: json (or csv / txt). The prompt previews the data and the underlying export_table tool returns the full payload as a single string ready to copy into Employer.json / Employer.csv / Employer.txt.

• create-rest-bp-endpoint — bp_class: MCPTest.BP.QueryService; leave other fields empty to accept the defaults the prompt proposes, or set them to match your existing production. With this repo’s docker compose, the web port is mapped to 9092 on the host; a typical run of the prompt registers a CSP/REST web application under /rest/user/... and a production item QueryService-REST-BS (EnsLib.REST.GenericService) that forwards to the QueryService business process. Before calling it, ensure demo data exists by invoking the run_class_method tool with class_name: MCPTest.Employer, method_name: PopulateAndAssign, args: [] (or rely on iris.script, which populates only when the table is still empty after import). Then validate the endpoint from a shell (-i prints response headers; on macOS/Linux use curl instead of curl.exe):

  # Employees for one employer (employer-id is required for this mode)
  curl.exe -sS -i "http://localhost:9092/rest/user/queryservice-rest-bs/QueryService-REST-BS" -H "service: employees" -H "employer-id: 1"
  All employers
  curl.exe -sS -i "http://localhost:9092/rest/user/queryservice-rest-bs/QueryService-REST-BS" -H "service: employers"
  

  Expected: HTTP/1.1 200 OK and Content-Type: application/json. The service header is matched case-insensitively; employee (singular) is accepted as an alias for employees. If your web path or business service Name in production differs, replace the URL segment after /rest/user/ and the final path segment (QueryService-REST-BS) accordingly.

1. Clone, then rename the package directory src/iris_mcp_blueprint/ and update the imports / entry point that reference it.
2. In pyproject.toml, change name, description, authors, and the [project.scripts] line so the CLI command and entry-point match the new package (my-mcp = "my_mcp.entrypoint:main").
3. Adjust IRIS-specific defaults in mcp_app.py if your server should default to a different host/port/namespace.
4. Add or remove handlers under tools/, prompts/, resources/. Each new module must be imported from entrypoint.py (or wherever mcp_app.run() is invoked) so the decorators register before the server starts.
5. Run uv sync once to refresh the lockfile, then uv run my-mcp --help to smoke-test the new CLI name.

uv init --package my-mcp           # creates pyproject.toml, src/my_mcp/, etc.
cd my-mcp
uv add fastmcp intersystems-irispython requests

Then, in src/my_mcp/mcp_app.py:

from fastmcp import FastMCP
mcp = FastMCP("my-mcp")

Add a tool in src/my_mcp/tools/echo.py:

from my_mcp.mcp_app import mcp
@mcp.tool()
def echo(message: str) -> str:
"""Return the message unchanged."""
return message

Add an entry point in src/my_mcp/entrypoint.py:

from my_mcp.mcp_app import mcp
def main() -> None:
mcp.run()

Wire it up in pyproject.toml:

[project.scripts]
my-mcp = "my_mcp.entrypoint:main"

Then uv run my-mcp launches the server over stdio.

The server reads these at startup with os.getenv(). Set them wherever you launch the server from (shell, mcp.json env block, Docker environment, CI secrets store). Note that there’s no automatic .env file loading.

For SSE / HTTP transport you can also set MCP_TRANSPORT, FASTMCP_HOST, and FASTMCP_PORT (see Run the server from the terminal below).

The server supports two transports. Pick the one that matches how the MCP client will reach it:

stdio (default — what Cursor / Claude Desktop normally use)

You usually do not start stdio mode by hand — your MCP client launches it for you using the JSON config in Configure Cursor or Claude Desktop. The same command works in a terminal if you want to verify it manually:

uv run iris-mcp-blueprint

The process now waits for an MCP client on stdin. Press Ctrl+C to stop. There is nothing to “open” in a browser; this transport is meant for a parent process.

sse (remote / HTTP)

Use this when the client cannot spawn the server itself — for example a remote IDE, a hosted assistant, or you want several users to share one server instance.

1. Start the server explicitly in SSE mode and bind it to an interface and port reachable by the client. 0.0.0.0 listens on all network interfaces; 127.0.0.1 is loopback-only.

   uv run iris-mcp-blueprint --transport sse --host 0.0.0.0 --port 8000
   

   Equivalent using environment variables (handy in docker run, systemd units, etc.):

   MCP_TRANSPORT=sse FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=8000 uv run iris-mcp-blueprint
   

   Defaults if you omit them: --transport stdio, --host 127.0.0.1, --port 8000 (these are also the values returned when --help is invoked).

2. Make sure firewalls / Docker / cloud security groups allow inbound traffic to that port from the client.

3. Point the client at the SSE endpoint. Replace <host> with the address that is reachable from the client (localhost if it’s the same machine, otherwise the public/LAN IP or DNS name); the path is always /sse:

   http://:8000/sse
   

   In Cursor, that goes in Settings → MCP → Add server (SSE / URL). In Claude Desktop, use a JSON entry such as:

   {
     "mcpServers": {
       "iris-mcp-blueprint": {
         "url": "http://:8000/sse",
         "env": {
           "IRIS_HOSTNAME": "localhost",
           "IRIS_PORT": "9091",
           "IRIS_WEB_PORT": "9092",
           "IRIS_NAMESPACE": "USER",
           "IRIS_USERNAME": "_SYSTEM",
           "IRIS_PASSWORD": "SYS"
         }
       }
     }
   }
   

4. Quick smoke-test from any host that can reach the URL — the SSE endpoint should keep the connection open and stream events (you’ll see event: / data: lines):

   curl -N http://:8000/sse
   

Security note: SSE mode does not add authentication on top — anyone who can reach the URL can call the tools (and therefore your IRIS instance). Bind to 127.0.0.1, put a reverse proxy in front, or run it inside a private network.

There are two distribution modes for any MCP client config: local (uv run against a clone you maintain locally) and remote (uvx pulling the package from GitHub or PyPI on demand). Pick one per server — they’re not meant to be combined.

1. Local: uv run against a cloned MCP

Clone this GitHub repository on a local folder and run the Docker container.

Cursor — create or edit .cursor/mcp.json in the repo root. Cursor uses the workspace folder as the MCP server’s working directory, so a plain uv command works without any extra path:

{
  "mcpServers": {
    "iris-mcp-blueprint": {
      "command": "uv",
      "args": ["run", "iris-mcp-blueprint"],
      "env": {
        "IRIS_HOSTNAME": "localhost",
        "IRIS_PORT": "9091",
        "IRIS_WEB_PORT": "9092",
        "IRIS_NAMESPACE": "USER",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS"
      }
    }
  }
}

Claude Desktop — Claude Desktop does not inherit a workspace folder, and on Windows the uv executable is often outside of Claude’s PATH. To make a local launch reliable you usually have to:

1. Point command at the absolute path to uv.exe (or to the uv binary on macOS / Linux).
2. Pass --directory <repo-root> to uv so it finds pyproject.toml.

Config file locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "iris-mcp-blueprint": {
      "command": "C:\\Users\\\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\path\\to\\iris-mcp-blueprint",
        "run",
        "iris-mcp-blueprint"
      ],
      "env": {
        "IRIS_HOSTNAME": "localhost",
        "IRIS_PORT": "9091",
        "IRIS_WEB_PORT": "9092",
        "IRIS_NAMESPACE": "USER",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS"
      }
    }
  }
}

2. Remote: uvx from GitHub or PyPI

uvx downloads the package, builds it in a temporary isolated environment, and runs it — no clone, no uv sync, no manual venv. The user only needs uv installed.

{
  "mcpServers": {
    "iris-mcp-blueprint": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/pietrodileo/iris-mcp-blueprint.git",
        "iris-mcp-blueprint"
      ],
      "env": {
        "IRIS_HOSTNAME": "localhost",
        "IRIS_PORT": "9091",
        "IRIS_WEB_PORT": "9092",
        "IRIS_NAMESPACE": "USER",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS"
      }
    }
  }
}

{
    "mcpServers": {
        "iris-mcp-blueprint": {
            "command": "C:\\Users\\p.dileo\\.local\\bin\\uvx.exe",
            "args": [
                "--from", "git+https://github.com/pietrodileo/iris-mcp-blueprint.git",
                "iris-mcp-blueprint"
            ],
            "env": {
                "IRIS_HOSTNAME": "localhost",
                "IRIS_PORT": "9091",
                "IRIS_WEB_PORT": "9092",
                "IRIS_NAMESPACE": "USER",
                "IRIS_USERNAME": "_SYSTEM",
                "IRIS_PASSWORD": "SYS"
            }
        }
    }
}

{
  "mcpServers": {
    "iris-mcp-blueprint": {
      "command": "uvx",
      "args": ["iris-mcp-blueprint"],
      "env": { "IRIS_HOSTNAME": "...", "IRIS_PORT": "1972" }
    }
  }
}

Once the project is ready to share, build a wheel and upload it to PyPI so anyone with uv installed can run it via uvx iris-mcp-blueprint without cloning the repo first.

1. Bump the version. PyPI rejects re-uploads of an existing version, so every release needs a new number. Use uv version to update pyproject.toml (and uv.lock) in one step:

   uv version --bump patch    # 0.1.0 -> 0.1.1
   uv version --bump minor    # 0.1.0 -> 0.2.0
   uv version --bump major    # 0.1.0 -> 1.0.0
   uv version 1.2.3           # set an explicit version
   uv version                 # just print the current version
   

2. Build distributable artifacts:

   uv build      # writes sdist + wheel into dist/
   

3. Get a PyPI token. Log in to PyPI and create an API token (project-scoped is recommended once the project exists; otherwise use an account-wide token for the first upload). The token always starts with pypi-.

4. Publish with the token. Export the token as UV_PUBLISH_TOKEN so it does not end up in your shell history; uv publish reads it automatically:

   # Linux / macOS / Git Bash
   export UV_PUBLISH_TOKEN=pypi-
   uv publish
   PowerShell
   $env:UV_PUBLISH_TOKEN = "pypi-"
   uv publish
   

5. Verify the public install (uses the freshly uploaded version, no git needed):

   uvx iris-mcp-blueprint --help
   

After a successful upload, switch any client mcp.json from the GitHub form to the simpler PyPI form shown above.