invgate-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InvGate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# invgate-mcp
+
+A curated [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server
+that exposes **12 read-only tools** over stdio for [InvGate Asset Management](https://www.invgate.com/asset-management).
+Any MCP-compatible client (Claude Desktop, etc.) can query assets, people,
+computers, servers, software, and API health through natural language.
+
+- **Transport**: stdio only (the universal default for local agents).
+- **Auth**: OAuth2 client-credentials flow (`scope=read`), in-memory token
+  cache with a 60-second expiry buffer and one-shot 401 retry.
+- **Validation**: every tool input is validated with [zod](https://zod.dev);
+  invalid input returns a structured `validation_error` without calling the API.
+- **Resilience**: HTTP, auth, and network failures are converted to MCP text
+  content with `isError: true` — the server never crashes the host.
+- **Distribution**: published to npm, runnable via `npx invgate-mcp`.
+
+## Install
+
+```bash
+# Run without installing
+npx invgate-mcp
+
+# Or install globally
+npm install -g invgate-mcp
+invgate-mcp
+```
+
+## Configuration
+
+The server reads three required environment variables at startup:
+
+| Env var | Description | Example |
+|---|---|---|
+| `INVGATE_BASE_URL` | InvGate public API base URL (ends with `/public-api/v2`) | `https://acme.invgate.net/public-api/v2` |
+| `INVGATE_CLIENT_ID` | OAuth2 client ID | `my-client-id` |
+| `INVGATE_CLIENT_SECRET` | OAuth2 client secret | `my-client-secret` |
+
+If any are missing the server prints a descriptive error to stderr and exits
+with code 1.
+
+The OAuth2 token endpoint is derived from `INVGATE_BASE_URL` by stripping the
+`/public-api/v2` segment and appending `/oauth2/token/`, so
+`https://acme.invgate.net/public-api/v2` → `https://acme.invgate.net/oauth2/token/`.
+
+## Claude Desktop config
+
+Add `invgate-mcp` to your `mcpServers` block
+(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "invgate": {
+      "command": "npx",
+      "args": ["-y", "invgate-mcp"],
+      "env": {
+        "INVGATE_BASE_URL": "https://acme.invgate.net/public-api/v2",
+        "INVGATE_CLIENT_ID": "your-client-id",
+        "INVGATE_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Input | Behavior |
+|---|---|---|
+| `invgate_list_asset_types` | _none_ | Returns all asset types |
+| `invgate_list_assets` | `page`, `per_page`, `asset_type_id`, `criteria` | Paginated asset list with optional filters |
+| `invgate_get_asset` | `asset_id` (required) | Single asset by ID |
+| `invgate_list_people` | `page`, `per_page`, `criteria` | Paginated people list |
+| `invgate_get_person` | `person_id` (required) | Single person by ID |
+| `invgate_get_person_assets` | `person_id` (required), `page`, `per_page` | Assets assigned to a person |
+| `invgate_list_computers` | `page`, `per_page`, `criteria` | Assets of type "computer" |
+| `invgate_get_computer` | `asset_id` (required) | Single computer asset |
+| `invgate_list_servers` | `page`, `per_page`, `criteria` | Assets of type "server" |
+| `invgate_get_server` | `asset_id` (required) | Single server asset |
+| `invgate_get_health` | _none_ | API connectivity status |
+| `invgate_list_software` | `page`, `per_page`, `criteria` | Paginated installed-software catalog |
+
+### Parameter mapping
+
+Tool inputs use `snake_case`; the server maps them to the InvGate API query
+parameters. `per_page` → `page_size`, `asset_type_id` → `asset_types`.
+The `criteria` object maps to InvGate's nested syntax:
+`{ "name": "cont:MacBook" }` becomes `criteria[name]=cont:MacBook` on the
+query string (`op` examples: `cont`, `eq`, `startswith`, …).
+
+### Results & errors
+
+- **Success**: the raw JSON response body, pretty-printed, as MCP `text` content.
+- **Errors**: structured JSON `{ "error": "...", "message": "...", "status": ... }`
+  as text content with `isError: true`. Types:
+  `validation_error`, `auth_error`, `api_error`, `network_error`.
+
+## Development
+
+```bash
+npm install
+npm run build       # tsup → dist/index.js (single ESM bundle)
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run (59 tests, MSW for HTTP interception)
+npm run test:coverage # vitest run --coverage (80% gate on src/**)
+npm run dev         # tsx src/index.ts
+```
+
+Requires Node.js 20+ (uses native `fetch`).
+
+## License
+
+MIT