Merge pull request #59 from influxdata/fix/pr-56-sync-main-retention

feat: Add Enterprise/Core retention policy support to update_database (supersedes #56)

Author: jstirnaman

.claude/skills/build-run-core-enterprise/SKILL.md

@@ -43,11 +43,11 @@ Copy `env.example` as a starting point: `cp env.example .env`
 
 ### Token types (Core/Enterprise)
 
-| Token Type | Purpose | How to obtain |
-|---|---|---|
-| Operator | Full admin, bootstraps the instance | Printed on first `influxdb3 serve` start |
-| Admin | Full admin except managing other admins | Created via `create_admin_token` tool |
-| Resource | Scoped read/write on specific databases | Created via `create_resource_token` tool |
+| Token Type | Purpose                                 | How to obtain                            |
+| ---------- | --------------------------------------- | ---------------------------------------- |
+| Operator   | Full admin, bootstraps the instance     | Printed on first `influxdb3 serve` start |
+| Admin      | Full admin except managing other admins | Created via `create_admin_token` tool    |
+| Resource   | Scoped read/write on specific databases | Created via `create_resource_token` tool |
 
 Use the operator token during initial setup. Create scoped resource tokens for
 applications.
@@ -105,6 +105,7 @@ npm run "MCP inspector"   # quotes required (space in script name)
 ```
 
 This launches the inspector connected to the built server. Use it to:
+
 - Call `health_check` to verify connectivity
 - Call `list_databases` to confirm data access
 - Test `execute_query` with a simple SQL query
@@ -113,27 +114,29 @@ This launches the inspector connected to the built server. Use it to:
 
 All tools available for Core/Enterprise instances:
 
-| Tool | Description |
-|---|---|
-| `health_check` | Verify connection and health status |
-| `list_databases` | List all databases |
-| `create_database` | Create a new database |
-| `delete_database` | Delete a database |
-| `execute_query` | Run SQL queries |
-| `get_measurements` | List tables in a database |
-| `get_measurement_schema` | Show columns/types for a table |
-| `write_line_protocol` | Write data via line protocol |
-| `create_admin_token` | Create named admin token |
-| `list_admin_tokens` | List admin tokens |
-| `create_resource_token` | Create scoped resource token |
-| `list_resource_tokens` | List resource tokens |
-| `delete_token` | Delete a token by name |
-| `regenerate_operator_token` | Regenerate operator token (destructive) |
-| `get_help` | Built-in help and troubleshooting |
-| `load_database_context` | Load custom context from `context/` |
-
-Tools like `update_database` and `cloud_*` token tools are **not** available
-for Core/Enterprise.
+| Tool                        | Description                                     |
+| --------------------------- | ----------------------------------------------- |
+| `health_check`              | Verify connection and health status             |
+| `list_databases`            | List all databases                              |
+| `create_database`           | Create a new database                           |
+| `update_database`           | Update retention period (Core requires v3.2.0+) |
+| `delete_database`           | Delete a database                               |
+| `execute_query`             | Run SQL queries                                 |
+| `get_measurements`          | List tables in a database                       |
+| `get_measurement_schema`    | Show columns/types for a table                  |
+| `write_line_protocol`       | Write data via line protocol                    |
+| `create_admin_token`        | Create named admin token                        |
+| `list_admin_tokens`         | List admin tokens                               |
+| `create_resource_token`     | Create scoped resource token                    |
+| `list_resource_tokens`      | List resource tokens                            |
+| `delete_token`              | Delete a token by name                          |
+| `regenerate_operator_token` | Regenerate operator token (destructive)         |
+| `get_help`                  | Built-in help and troubleshooting               |
+| `load_database_context`     | Load custom context from `context/`             |
+
+For Core/Enterprise, `update_database` supports the retention period only
+(updating retention on Core requires v3.2.0+). The `cloud_*` token tools are
+**not** available for Core/Enterprise.
 
 ## Troubleshooting
 
@@ -145,6 +148,7 @@ and `INFLUX_DB_PRODUCT_TYPE` is exactly `core` or `enterprise`.
 ### Health check fails but server starts
 
 The server can start without a reachable InfluxDB instance. Check:
+
 1. InfluxDB is running: `curl http://localhost:8181/ping`
 2. Token is valid (operator or admin token for full access)
 3. URL has trailing slash if using the default config

.claude/skills/build-run-core-enterprise/references/mcp-client-configs.md

@@ -59,11 +59,16 @@ Use `host.docker.internal` to reach InfluxDB running on the Docker host:
     "influxdb": {
       "command": "docker",
       "args": [
-        "run", "--rm", "-i",
+        "run",
+        "--rm",
+        "-i",
         "--add-host=host.docker.internal:host-gateway",
-        "-e", "INFLUX_DB_INSTANCE_URL",
-        "-e", "INFLUX_DB_TOKEN",
-        "-e", "INFLUX_DB_PRODUCT_TYPE",
+        "-e",
+        "INFLUX_DB_INSTANCE_URL",
+        "-e",
+        "INFLUX_DB_TOKEN",
+        "-e",
+        "INFLUX_DB_PRODUCT_TYPE",
         "influxdb-mcp-server"
       ],
       "env": {
@@ -87,10 +92,15 @@ When InfluxDB is on a separate host, use the remote URL directly (no
     "influxdb": {
       "command": "docker",
       "args": [
-        "run", "--rm", "-i",
-        "-e", "INFLUX_DB_INSTANCE_URL",
-        "-e", "INFLUX_DB_TOKEN",
-        "-e", "INFLUX_DB_PRODUCT_TYPE",
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "INFLUX_DB_INSTANCE_URL",
+        "-e",
+        "INFLUX_DB_TOKEN",
+        "-e",
+        "INFLUX_DB_PRODUCT_TYPE",
         "influxdb-mcp-server"
       ],
       "env": {

.claude/skills/testing/SKILL.md

@@ -87,18 +87,18 @@ Reruns on file changes. Useful during development.
 
 ## What the Tests Cover
 
-| Test | What it verifies |
-|---|---|
-| Initialize handshake | Server starts, SDK handshake succeeds, capabilities reported |
-| Server version | Name is `"influxdb-mcp-server"`, version is defined |
-| Tool count | `tools/list` returns exactly `EXPECTED_TOOL_COUNT` tools |
-| Tool structure | Each tool has `name`, `description`, `inputSchema` with `type: "object"` |
-| Core tool names | Spot-checks `health_check`, `execute_query`, `write_line_protocol`, `list_databases`, `create_admin_token` |
-| Resource URIs | 4 resources with correct `influx://` URIs |
-| Resource structure | Each resource has `name`, `uri`, `description` |
-| Prompt names | 3 prompts: `list-databases`, `check-health`, `load-context` |
-| Ping | Server responds to ping |
-| Unknown tool error | Calling nonexistent tool throws `McpError` |
+| Test                 | What it verifies                                                                                           |
+| -------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Initialize handshake | Server starts, SDK handshake succeeds, capabilities reported                                               |
+| Server version       | Name is `"influxdb-mcp-server"`, version is defined                                                        |
+| Tool count           | `tools/list` returns exactly `EXPECTED_TOOL_COUNT` tools                                                   |
+| Tool structure       | Each tool has `name`, `description`, `inputSchema` with `type: "object"`                                   |
+| Core tool names      | Spot-checks `health_check`, `execute_query`, `write_line_protocol`, `list_databases`, `create_admin_token` |
+| Resource URIs        | 4 resources with correct `influx://` URIs                                                                  |
+| Resource structure   | Each resource has `name`, `uri`, `description`                                                             |
+| Prompt names         | 3 prompts: `list-databases`, `check-health`, `load-context`                                                |
+| Ping                 | Server responds to ping                                                                                    |
+| Unknown tool error   | Calling nonexistent tool throws `McpError`                                                                 |
 
 ## Analyzing Failures
 
@@ -112,6 +112,7 @@ The most common failure after code changes. The constant in
 below for documentation.
 
 To find the current count, start the server briefly and check stderr:
+
 ```bash
 npm run build && INFLUX_DB_INSTANCE_URL=http://localhost:19999/ \
 INFLUX_DB_TOKEN=fake INFLUX_DB_PRODUCT_TYPE=core \
@@ -122,6 +123,7 @@ sleep 1 && kill $!
 Look for: `[MCP] Server initialized with N tools, N resources, N prompts`
 
 The tool count breakdown by category file:
+
 - `help.tools.ts` (2) + `write.tools.ts` (1) + `database.tools.ts` (4)
 - `query.tools.ts` (3) + `token.tools.ts` (6) + `cloud-token.tools.ts` (5)
 - `health.tools.ts` (1) = **22 total**
@@ -136,13 +138,15 @@ message if the build artifact is missing.
 ### Initialize handshake timeout
 
 The server process failed to start. Common causes:
+
 - Build is stale after source changes — rebuild with `npm run build`
 - Missing or invalid env vars — protocol tests use a fake config internally,
   so this usually means `createTestClient` was called with bad overrides
 
 ### Integration test: "HEALTHY" not found
 
 InfluxDB instance is unreachable or unhealthy. Verify:
+
 1. Instance is running: `curl http://localhost:8181/ping`
 2. Token is valid
 3. `INFLUX_DB_PRODUCT_TYPE` matches the actual instance type
@@ -181,6 +185,59 @@ The `createTestClient(env?)` factory in `tests/helpers/mcp-client.ts` spawns
 a real server process and returns a connected MCP `Client`. Override env vars
 by passing a partial record. Always call `close()` in `afterAll`.
 
+## Reviewing data-plane and admin changes
+
+When a change adds or modifies a tool that talks to an InfluxDB endpoint
+(writes, queries, database/token management), verify the actual API contract
+and exercise it against a real instance. Tool descriptions, CHANGELOG entries,
+and code comments are not authoritative on their own — confirm them.
+
+### Verify the API contract first
+
+Confirm the HTTP method, path, and request/response shape against both the
+InfluxData docs knowledge source and the `influxdata/influxdb` source
+(`influxdb3_server/src/http.rs` routing, `influxdb3_types/src/http.rs` structs).
+
+Gotchas that have already bitten this repo:
+
+- Core/Enterprise `update_database` retention is `PUT /api/v3/configure/database`
+  with `retention_period` as a duration string (`"60d"`) — not `PATCH`, not
+  `retention_period_ns`.
+- Core can update retention since v3.2.0 (static docs wrongly say it's immutable).
+- `/ping` and `/health` use `Token` auth even for core/enterprise (v1/v2 compat);
+  the admin client uses `Bearer`. Both are intentional.
+
+### Exercise it against a real instance
+
+Admin endpoints (`/api/v3/configure/*`) need an admin token; `health_check`
+does not, so a passing `health_check` does not prove the token works. Run a
+self-contained Core for an admin-path test on a free port:
+
+```bash
+docker run -d --name mcp-it-core -p 8383:8181 \
+  -v "$PWD/tests/fixtures/admin-token.json":/admin-token.json:ro \
+  influxdb:3-core influxdb3 serve \
+  --node-id local-test --object-store memory \
+  --admin-token-file /admin-token.json
+
+INFLUX_TEST_ENABLED=true INFLUX_DB_INSTANCE_URL=http://localhost:8383/ \
+INFLUX_DB_TOKEN=apiv3_test INFLUX_DB_PRODUCT_TYPE=core \
+npx vitest run tests/integration.test.ts
+
+docker rm -f mcp-it-core
+```
+
+This uses the offline preconfigured admin token in `tests/fixtures/admin-token.json`
+(token `apiv3_test`) — the `docker-compose.test.yml` pattern, but on a port you
+choose so it does not collide with other local instances.
+
+### Token gotcha
+
+v3 tokens are base64 and can contain `+`, `/`, and `=`. Do not extract one with
+`grep -oE 'apiv3_[A-Za-z0-9_-]+'` — it truncates at the first base64 character
+and yields an invalid token (the server returns `401 "the request was not
+authenticated"`).
+
 ## Additional Resources
 
 ### Reference Files

.claude/skills/testing/references/test-architecture.md

@@ -25,7 +25,7 @@ The trick: `createTestClient()` passes a fake config:
 
 ```typescript
 const BASE_ENV = {
-  INFLUX_DB_INSTANCE_URL: "http://localhost:19999/",  // nothing listens here
+  INFLUX_DB_INSTANCE_URL: "http://localhost:19999/", // nothing listens here
   INFLUX_DB_TOKEN: "test-token-not-used",
   INFLUX_DB_PRODUCT_TYPE: "core",
 };
@@ -106,7 +106,7 @@ exist, and skips gracefully if not (rather than failing on an empty instance).
 ```
 
 - **15s timeouts**: Generous for slow CI machines where child process spawn
-  + initialize handshake can take 2-3 seconds
+  - initialize handshake can take 2-3 seconds
 - **No pool override**: Default vitest forks handle child process spawning
 - **No `rootDir` change to tsconfig**: vitest uses Vite's esbuild pipeline
   to compile test files independently from `tsc`. The production tsconfig
@@ -127,6 +127,7 @@ For integration tests that need InfluxDB, use the same
 ## Local Docker Infrastructure
 
 `docker-compose.test.yml` starts InfluxDB 3 Core with:
+
 - `--object-store memory` — ephemeral, no volumes
 - Docker secrets to inject `tests/fixtures/admin-token.json` as
   `--admin-token-file=/run/secrets/admin-token`
@@ -151,6 +152,7 @@ Uses `docker run` (not `services:`) because Core requires
 cannot pass container CMD arguments.
 
 The job:
+
 1. Checks out the repo (which includes `tests/fixtures/admin-token.json`)
 2. Bind-mounts the token file into the container at `/run/secrets/admin-token`
 3. Polls `/ping` until Core is ready (up to 30 seconds)

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     name: Version consistency check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
 
@@ -40,11 +40,11 @@ jobs:
     name: Protocol tests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: "22"
           cache: "npm"
@@ -57,11 +57,11 @@ jobs:
     name: Integration tests (InfluxDB 3 Core)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: "22"
           cache: "npm"
@@ -113,11 +113,11 @@ jobs:
        github.event.pull_request.head.repo.full_name == github.repository)
     environment: cloud-serverless
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f  # v6.3.0
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: "22"
           cache: "npm"

.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all"
+}