Add multi-project support via config file

.github/workflows/ci.yml

@@ -46,5 +46,3 @@ jobs:
 
     - name: Run end-to-end tests
       run: npm run test:e2e
-      env:
-        ROLLBAR_E2E_READ_TOKEN: ${{ secrets.ROLLBAR_E2E_READ_TOKEN }}

.gitignore

@@ -1,4 +1,5 @@
 .env
+.rollbar-mcp.json
 
 node_modules/
 build/

CONTRIBUTING.md

@@ -6,22 +6,30 @@ Contributions are welcome.
 
 Install and build:
 
-```
+```bash
 npm install
 npm run build
 ```
 
-Run your local installation from Claude Code:
+You can run the server directly to confirm it starts (it will wait for stdin; Ctrl+C to stop):
 
+```bash
+node build/index.js
 ```
+
+For local development, configure Rollbar either with an environment variable or a config file. Create `.rollbar-mcp.json` in the project root (or set `ROLLBAR_CONFIG_FILE` to its path) for single- or multi-project config—see the README Configuration section.
+
+### Run your local installation from Claude Code
+
+In your Claude Code MCP config (e.g. `.mcp.json`):
+
+```json
 {
   "mcpServers": {
     "rollbar": {
       "type": "stdio",
       "command": "node",
-      "args": [
-        "/ABSOLUTE/PATH/TO/rollbar-mcp-server/build/index.js"
-      ],
+      "args": ["/ABSOLUTE/PATH/TO/rollbar-mcp-server/build/index.js"],
       "env": {
         "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
       }
@@ -30,19 +38,42 @@ Run your local installation from Claude Code:
 }
 ```
 
-Add `ROLLBAR_API_BASE` to the `env` map if you need to point the server at a custom Rollbar API endpoint (for example, `"ROLLBAR_API_BASE": "https://rollbar-dev.example.com/api/1"`).
+To use a config file instead, set `"ROLLBAR_CONFIG_FILE": "/path/to/.rollbar-mcp.json"` in `env` (or omit it if `.rollbar-mcp.json` is in the project root or your home directory). Add `ROLLBAR_API_BASE` to `env` if you need a custom Rollbar API endpoint (e.g. `"ROLLBAR_API_BASE": "https://rollbar-dev.example.com/api/1"`).
+
+### Run your local installation from your IDE
 
-Run your local installation from VSCode:
+1. Open **Cursor Settings** (Cmd+, or File → Preferences).
+2. Go to **Cursor Settings → Features → MCP** (or search for “MCP”).
+3. Edit the MCP config and add a server that runs your local build:
 
+```json
+{
+  "mcpServers": {
+    "rollbar": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/rollbar-mcp-server/build/index.js"],
+      "env": {
+        "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
+      }
+    }
+  }
+}
 ```
+
+Replace `/ABSOLUTE/PATH/TO/rollbar-mcp-server` with the real path to your clone. To use a config file instead, set `"ROLLBAR_CONFIG_FILE": "/path/to/.rollbar-mcp.json"` in `env`. Save and restart Cursor (or reload the window) so the new server is picked up. In a new Agent/Composer chat, the Rollbar tools (e.g. `list-projects`, `get-item-details`) will be available.
+
+### Run your local installation from VS Code
+
+In your `.vscode/mcp.json`:
+
+```json
 {
   "servers": {
     "rollbar": {
       "type": "stdio",
       "command": "node",
-      "args": [
-        "/ABSOLUTE/PATH/TO/rollbar-mcp-server/build/index.js"
-      ],
+      "args": ["/ABSOLUTE/PATH/TO/rollbar-mcp-server/build/index.js"],
       "env": {
         "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
       }
@@ -51,10 +82,23 @@ Run your local installation from VSCode:
 }
 ```
 
-You can test an individual tool using the `@modelcontextprotocol/inspector` module. For example, test the tool `get-item-details` with arg `counter=2455389`:
+You can use `ROLLBAR_CONFIG_FILE` in `env` instead of `ROLLBAR_ACCESS_TOKEN` for config-file-based setup.
+
+## Testing
+
+Test an individual tool with the MCP inspector. List tools:
 
+```bash
+npx @modelcontextprotocol/inspector --cli -e ROLLBAR_ACCESS_TOKEN=$TOKEN node build/index.js --method tools/list --debug
 ```
+
+Call a tool (e.g. `list-projects` or `get-item-details`):
+
+```bash
+npx @modelcontextprotocol/inspector --cli -e ROLLBAR_ACCESS_TOKEN=$TOKEN node build/index.js --method tools/call --tool-name list-projects --debug
 npx @modelcontextprotocol/inspector --cli -e ROLLBAR_ACCESS_TOKEN=$TOKEN node build/index.js --method tools/call --tool-name get-item-details --tool-arg counter=2455389 --debug
 ```
 
-To run the e2e tests, you'll need a read token in the env var ROLLBAR_E2E_READ_TOKEN, which should be a read-scope project access token for a Rollbar project that has items inside, including an item with counter #8.
+Replace `$TOKEN` with your Rollbar access token (or use a config file and set `ROLLBAR_CONFIG_FILE` in the env).
+
+The full e2e suite (`npm run test:e2e`) runs two scripts: the npx-install test (no token needed) and the get-item-details test. If `ROLLBAR_E2E_READ_TOKEN` is not set, the get-item-details test is skipped and the suite still passes. To run that test, set `ROLLBAR_E2E_READ_TOKEN` to a read-scope project access token for a Rollbar project that has items, including an item with counter #8.

README.md

@@ -4,47 +4,81 @@ A Model Context Protocol (MCP) server for [Rollbar](https://rollbar.com).
 
 ## Features
 
-This MCP server implementes the `stdio` server type, which means your AI tool (e.g. Claude) will run it directly; you don't run a separate process or connect over http.
+This MCP server implements the `stdio` server type, which means your AI tool (e.g. Claude, Cursor) will run it directly; you don't run a separate process or connect over http.
 
 ### Configuration
 
-- `ROLLBAR_ACCESS_TOKEN`: an access token for your Rollbar project with `read` and/or `write` scope.
-- `ROLLBAR_API_BASE` (optional): override the Rollbar API base URL (defaults to `https://api.rollbar.com/api/1`). Use this when running against a staging or development Rollbar deployment.
+**Single Project: Environment variable (single project, backward compatible)**
+
+- `ROLLBAR_ACCESS_TOKEN`: access token for your Rollbar project.
+- `ROLLBAR_API_BASE` (optional): override the API base URL (defaults to `https://api.rollbar.com/api/1`).
+
+**Multiple Project: Config file (single or multiple projects)**
+
+Create `.rollbar-mcp.json` in your working directory or home directory, or set `ROLLBAR_CONFIG_FILE` to point to a custom path. A checked-in template is available at `rollbar-mcp-example.json`; copy it to `.rollbar-mcp.json` and fill in your real tokens.
+
+Single project shorthand:
+
+```json
+{ "token": "tok_abc123" }
+```
+
+Multiple projects:
+
+```json
+{
+  "projects": [
+    { "name": "backend",  "token": "tok_abc123" },
+    { "name": "frontend", "token": "tok_xyz789" },
+    { "name": "staging",  "token": "tok_stg456", "apiBase": "https://rollbar-staging.example.com/api/1" }
+  ]
+}
+```
+
+Config file lookup order:
+
+1. `ROLLBAR_CONFIG_FILE` env var
+2. `.rollbar-mcp.json` in current working directory
+3. `~/.rollbar-mcp.json` in home directory
+4. `ROLLBAR_ACCESS_TOKEN` env var (single project, backward compatible)
+
+If a config file exists but is invalid, the server exits with an error instead of falling back to a lower-priority config source.
 
 ### Tools
 
-`get-item-details(counter, max_tokens?)`: Given an item number, fetch the item details and last occurrence details. Supports an optional `max_tokens` parameter (default: 20000) to automatically truncate large occurrence responses. Example prompt: `Diagnose the root cause of Rollbar item #123456`
+`list-projects()`: List configured Rollbar projects (names and apiBase only; tokens are never returned). Use this when multiple projects are configured to see which project names you can pass to other tools.
+
+`get-item-details(counter, max_tokens?, project?)`: Given an item number, fetch the item details and last occurrence details. Supports an optional `max_tokens` parameter (default: 20000) to automatically truncate large occurrence responses. Optional `project` selects which configured project to use when multiple are defined. Example prompt: `Diagnose the root cause of Rollbar item #123456`
 
-`get-deployments(limit)`: List deploy data for the given project. Example prompt: `List the last 5 deployments` or `Are there any failed deployments?`
+`get-deployments(limit, project?)`: List deploy data for the given project. Optional `project` when multiple projects are configured. Example prompt: `List the last 5 deployments` or `Are there any failed deployments?`
 
-`get-version(version, environment)`: Fetch version details for the given version string, environment name, and the configured project.
+`get-version(version, environment, project?)`: Fetch version details for the given version string and environment. Optional `project` when multiple projects are configured.
 
-`get-top-items(environment)`: Fetch the top items in the last 24 hours given the environment name, and the configured project.
+`get-top-items(environment, project?)`: Fetch the top items in the last 24 hours for the given environment. Optional `project` when multiple projects are configured.
 
-`list-items(environment)`: List items filtered by status, environment and a search query.
+`list-items(status?, level?, environment?, page?, limit?, query?, project?)`: List items filtered by status, environment, and search query. Optional `project` when multiple projects are configured.
 
-`get-replay(environment, sessionId, replayId, delivery?)`: Retrieve session replay metadata and payload for a specific session in the configured project. By default the tool writes the replay JSON to a temporary file (under your system temp directory) and returns the path so any client can inspect it. Set `delivery="resource"` to receive a `rollbar://replay/<environment>/<sessionId>/<replayId>` link for MCP-aware clients. Example prompt: `Fetch the replay 789 from session abc in staging`.
+`get-replay(environment, sessionId, replayId, delivery?, project?)`: Retrieve session replay metadata and payload for a specific session. By default the tool writes the replay JSON to a temporary file (under your system temp directory) and returns the path. Set `delivery="resource"` to receive a `rollbar://replay/<environment>/<sessionId>/<replayId>` link for MCP-aware clients. Optional `project` when multiple projects are configured. `delivery="resource"` is only supported in single-project mode; when multiple projects are configured, use `delivery="file"` with a `project` parameter instead. Example prompt: `Fetch the replay 789 from session abc in staging`.
 
-`update-item(itemId, status?, level?, title?, assignedUserId?, resolvedInVersion?, snoozed?, teamId?)`: Update an item's properties including status, level, title, assignment, and more. Example prompt: `Mark Rollbar item #123456 as resolved` or `Assign item #123456 to user ID 789`. (Requires `write` scope)
+`update-item(itemId, status?, level?, title?, assignedUserId?, resolvedInVersion?, snoozed?, teamId?, project?)`: Update an item's properties including status, level, title, assignment, and more. Optional `project` when multiple projects are configured. Example prompt: `Mark Rollbar item #123456 as resolved` or `Assign item #123456 to user ID 789`. (Requires `write` scope)
 
 ## How to Use
 
 Tested with node 20 and 22 (`nvm use 22`).
 
 ### Claude Code
 
-Configure your `.mcp.json` as follows:
+Configure your `.mcp.json` as follows.
 
-```
+Using an environment variable (single project):
+
+```json
 {
   "mcpServers": {
     "rollbar": {
       "type": "stdio",
       "command": "npx",
-      "args": [
-        "-y",
-        "@rollbar/mcp-server@latest"
-      ],
+      "args": ["-y", "@rollbar/mcp-server@latest"],
       "env": {
         "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
       }
@@ -53,58 +87,118 @@ Configure your `.mcp.json` as follows:
 }
 ```
 
-Optionally include `ROLLBAR_API_BASE` in the `env` block to target a non-production API endpoint, for example `"ROLLBAR_API_BASE": "https://rollbar-dev.example.com/api/1"`.
+Optionally include `ROLLBAR_API_BASE` in the `env` block to target a non-production API endpoint.
+
+Using a config file (single or multiple projects):
+
+```json
+{
+  "mcpServers": {
+    "rollbar": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@rollbar/mcp-server@latest"],
+      "env": {
+        "ROLLBAR_CONFIG_FILE": "/path/to/.rollbar-mcp.json"
+      }
+    }
+  }
+}
+```
 
 
 ### Codex CLI
 
 Add to your `~/.codex/config.toml`:
 
+```toml
+[mcp_servers.rollbar]
+command = "npx"
+args = ["-y", "@rollbar/mcp-server@latest"]
+env = { "ROLLBAR_ACCESS_TOKEN" = "<project read/write access token>" }
 ```
+
+Or with a config file:
+
+```toml
 [mcp_servers.rollbar]
 command = "npx"
 args = ["-y", "@rollbar/mcp-server@latest"]
-env = { "ROLLBAR_ACCESS_TOKEN" = "<project read/write acecss token>" }
+env = { "ROLLBAR_CONFIG_FILE" = "/path/to/.rollbar-mcp.json" }
 ```
 
 
 ### Junie
 
-Configure your `.junie/mcp/mcp.json` as follows:
+Configure your `.junie/mcp/mcp.json` as follows (env var or `ROLLBAR_CONFIG_FILE` for config file):
 
+```json
+{
+  "mcpServers": {
+    "rollbar": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@rollbar/mcp-server@latest"],
+      "env": {
+        "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
+      }
+    }
+  }
+}
+```
+
+
+### Cursor
+
+Configure Cursor’s MCP servers (Cursor Settings → Features → MCP, or search for “MCP” in settings). Use either an environment variable or a config file.
+
+With an environment variable (single project):
+
+```json
+{
+  "mcpServers": {
+    "rollbar": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@rollbar/mcp-server@latest"],
+      "env": {
+        "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
+      }
+    }
+  }
+}
 ```
+
+With a config file (single or multiple projects):
+
+```json
 {
-    "mcpServers": {
-        "rollbar": {
-            "type": "stdio",
-            "command": "npx",
-            "args": [
-                "-y",
-                "@rollbar/mcp-server@latest"
-            ],
-            "env": {
-                "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
-            }
-        }
+  "mcpServers": {
+    "rollbar": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@rollbar/mcp-server@latest"],
+      "env": {
+        "ROLLBAR_CONFIG_FILE": "/path/to/.rollbar-mcp.json"
+      }
     }
+  }
 }
 ```
 
+Restart Cursor (or reload the window) after changing MCP settings. To use a local build instead of npx, see CONTRIBUTING.md.
 
 ### VS Code
 
-Configure your `.vscode/mcp.json` as follows:
+Configure your `.vscode/mcp.json` as follows (env var or `ROLLBAR_CONFIG_FILE` for config file):
 
-```
+```json
 {
   "servers": {
     "rollbar": {
       "type": "stdio",
       "command": "npx",
-      "args": [
-        "-y",
-        "@rollbar/mcp-server@latest"
-      ],
+      "args": ["-y", "@rollbar/mcp-server@latest"],
       "env": {
         "ROLLBAR_ACCESS_TOKEN": "<project read/write access token>"
       }
@@ -113,4 +207,4 @@ Configure your `.vscode/mcp.json` as follows:
 }
 ```
 
-Or using a local development installation - see CONTRIBUTING.md.
+Or using a local development installation—see CONTRIBUTING.md.

rollbar-mcp-example.json

@@ -0,0 +1,13 @@
+{
+  "projects": [
+    {
+      "name": "backend",
+      "token": "tok_backend_example",
+      "apiBase": "https://api.rollbar.com/api/1"
+    },
+    {
+      "name": "frontend",
+      "token": "tok_frontend_example"
+    }
+  ]
+}