@aaa-sentinel/mcp-server 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AAA Sentinel
+
+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

@@ -1,3 +1,167 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @aaa-sentinel/mcp-server
+
+Lets an AI assistant read your cloud cost data — accounts, scans, findings, savings and
+chargeback — through the [Model Context Protocol](https://modelcontextprotocol.io), so you can
+ask *"which of my AWS accounts is bleeding the most money this month, and why"* in the chat
+window you already have open instead of a dashboard you have to remember to visit.
+
+> **User** — Which account has the most waste right now?
+>
+> **Assistant** *(calls `list_accounts`, then `get_reports_summary`, then `list_findings`)* —
+> `prod-eu-west-1` accounts for $4,180/mo of the $9,240 total, and $1,730 of that is recoverable:
+> 11 unattached EBS volumes ($412/mo), 3 idle RDS instances ($980/mo) and an over-provisioned
+> NAT gateway ($338/mo).
+
+## Requirements
+
+- Node.js 20 or newer.
+- An OAuth2 application created in the [developer portal](https://app.aaa-sentinel.com/developer/apps).
+- Scopes depend on what you want the assistant to be able to read — see the table below. Grant
+  only those; the scopes you leave out are simply not reachable from the assistant.
+- A **Pro** plan for `get_reports_summary`, `list_savings`, `get_dashboard`, `get_cost_forecast`
+  and the security tools (which also need the security add-on on the account), **Business** for
+  `get_chargeback` and `list_cost_anomalies`. The other tools work on any paid plan.
+
+## Configuration
+
+The server speaks stdio: your MCP client launches it as a child process and keeps it alive. All
+clients use the same shape of configuration file.
+
+**Claude Desktop** — `claude_desktop_config.json`
+(`%APPDATA%\Claude` on Windows, `~/Library/Application Support/Claude` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "aaa-sentinel": {
+      "command": "npx",
+      "args": ["--yes", "@aaa-sentinel/mcp-server"],
+      "env": {
+        "AAA_SENTINEL_MCP_CLIENT_ID": "your-client-id",
+        "AAA_SENTINEL_MCP_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+**VS Code** — `.vscode/mcp.json`, using an input so the secret is never written to a file that
+could be committed:
+
+```json
+{
+  "inputs": [
+    { "id": "sentinel-secret", "type": "promptString", "description": "AAA Sentinel client secret", "password": true }
+  ],
+  "servers": {
+    "aaa-sentinel": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--yes", "@aaa-sentinel/mcp-server"],
+      "env": {
+        "AAA_SENTINEL_MCP_CLIENT_ID": "your-client-id",
+        "AAA_SENTINEL_MCP_CLIENT_SECRET": "${input:sentinel-secret}"
+      }
+    }
+  }
+}
+```
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `AAA_SENTINEL_MCP_CLIENT_ID` | yes | Client ID of the OAuth2 application |
+| `AAA_SENTINEL_MCP_CLIENT_SECRET` | yes | Client secret. Treat it as a password |
+| `AAA_SENTINEL_MCP_BASE_URL` | no | Defaults to `https://api.aaa-sentinel.com`. Must be `https` — the secret is never sent over plain HTTP |
+| `AAA_SENTINEL_MCP_DEBUG` | no | Set to `1` to print one line to stderr per tool call with the number of API requests used so far. Off by default |
+
+If a credential is missing or the base URL is not `https`, the process prints one line to
+**stderr** and exits with code 1. It does not start half-configured: a client that believes it is
+connected to a server that can answer nothing is worse than a client that reports a failure.
+
+## Tools
+
+All fourteen are **read-only**.
+
+| Tool | Arguments | Scope | Plan |
+| --- | --- | --- | --- |
+| `list_accounts` | — | `accounts:read` | any |
+| `list_scans` | `accountId` | `scans:read` | any |
+| `get_scan` | `scanId` | `scans:read` | any |
+| `list_findings` | `scanId`, `includeSuppressed?` | `findings:read` | any |
+| `get_reports_summary` | `accountId?` | `reports:read` | Pro |
+| `list_savings` | `accountId?`, `type?` | `savings:read` | Pro |
+| `get_chargeback` | `clientId?` | `reports:read` | Business |
+| `get_dashboard` | `accountId?` | `dashboard:read` | Pro |
+| `get_cost_forecast` | `accountId` | `reports:read` | Pro |
+| `list_cost_anomalies` | `accountId?` | `reports:read` | Business |
+| `get_security_overview` | — | `security:read` | Pro + security add-on |
+| `get_security_score` | `accountId` | `security:read` | Pro + security add-on |
+| `list_security_findings` | `accountId`, `source?` | `security:read` | Pro + security add-on |
+| `get_security_conformance` | `accountId` or `clientId` | `security:read` (+ `reports:read` for `clientId`) | Pro (Business for `clientId`) |
+
+`type` is one of `compute`, `storage`, `network`, `database`, `serverless`, `governance`.
+`source` is one of `own`, `corroborated`, `securityhub`, `guardduty`, `defender`, `scc`.
+
+The security tools need the security add-on enabled on the account (20 €/month per account).
+Without it they answer with `access: "teaser"` and no scan data, so the assistant can tell
+"not enabled" apart from "nothing found".
+
+### Why there is nothing that writes
+
+There is no tool to approve a remediation, launch a playbook, stop an instance, start a security
+scan or enable the (billed) security add-on, and that is a
+decision rather than a gap. An MCP server with write access puts a model — with its own idea of
+what is convenient, and a prompt an attacker may have influenced — inside the path that changes
+your infrastructure. Execution stays in the product, where it is gated by approvals, dry runs and
+an audit trail. The assistant reads and reasons; it does not act.
+
+The same reasoning applies to the scopes: an OAuth2 application registered with only
+`accounts:read` and `findings:read` cannot be talked into doing anything else, no matter what the
+conversation contains.
+
+## Rate limits and quota
+
+Calls made through this server count against the same monthly quota and per-minute burst limit as
+any other API client, and they are billed to the same plan. An assistant that loops over every
+account calling `list_findings` will consume quota quickly — the usage page in the portal shows
+the consumption per application, so keep this server on its own OAuth2 application if you want to
+be able to tell its traffic apart from your CI's.
+
+The server holds a single access token in memory, refreshes it a minute before it expires, and
+serialises concurrent refreshes into one request. Every tool costs exactly one API request — none
+of them paginates or fans out — so the burst limit maps directly to tool calls per minute. `429`
+and `5xx` responses are retried with backoff, honouring `Retry-After` unless the server asks for
+more than 10 seconds; when it asks for longer, the error carries the wait so the assistant can
+tell you instead of retrying blindly.
+
+What the numbers above do **not** tell you is how many tools your assistant chains together to
+answer one question — that is decided by the model, not by us, and it is the multiplier that
+decides whether the limit is comfortable. Set `AAA_SENTINEL_MCP_DEBUG=1`, ask a few of your real
+questions, and read the running count from your client's MCP log:
+
+```
+[mcp] list_accounts — API requests: 1 in the last 60s, 1 total (tokens: 1)
+[mcp] list_findings — API requests: 2 in the last 60s, 2 total (tokens: 1)
+```
+
+The first number is the one to watch: it is counted over a rolling minute, which is the same
+unit as the burst limit, so you can compare it with your plan without doing arithmetic.
+
+## Troubleshooting
+
+**The client shows the server as failed and there is no output.** Look at your client's MCP log,
+not at stdout: stdout carries only protocol messages, so every diagnostic goes to stderr. The
+usual cause is a missing `AAA_SENTINEL_MCP_CLIENT_ID` or `AAA_SENTINEL_MCP_CLIENT_SECRET`.
+
+**Tools appear but every call answers with an error mentioning HTTP 403.** The OAuth2 application
+does not have the scope that tool needs, or your plan does not include it. Scopes are fixed when
+the application is created — register a new one rather than trying to widen the old one.
+
+**A tool answers with HTTP 429.** You reached the per-minute burst limit of your plan. The error
+states how many seconds are left; it clears on its own, and asking the assistant to work over
+fewer accounts at a time is usually enough.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The licence covers this client only; access to the API is governed by
+the terms of service at <https://app.aaa-sentinel.com>.