fix(mcp): close P1/P2 ledger findings — README drift, server.json scope, sdk pin, create_vector tool (#13)

Squash-merged via triage. Rebased onto master (after #12 + #11). Added test fixture fixes: EXPECTED_TOOLS 16→17, /vector/new route in mock. Closes B16-F7 (README), F8 (server.json), F9 (SDK pin), F10 (create_vector).

Author: mastermanas805

README.md

@@ -107,6 +107,7 @@ to reach for this MCP, see <https://instanode.dev/agent.html>.
 | Tool              | Description                                                                                                                                                       |
 |-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `create_postgres` | `POST /db/new` — Provision a Postgres database (pgvector included). Returns `connection_url` + the `note`/`upgrade` claim URL. `name` required.                   |
+| `create_vector`   | `POST /vector/new` — Provision a pgvector-enabled Postgres database (embedding store). Returns `connection_url` + `extension`/`dimensions` + `note`/`upgrade`. `name` required; optional `dimensions` is a documentation hint. |
 | `create_cache`    | `POST /cache/new` — Provision a Redis cache (ACL-scoped user + namespace). Returns `connection_url` + `note`/`upgrade`. `name` required.                          |
 | `create_nosql`    | `POST /nosql/new` — Provision a MongoDB database (per-resource user + DB-scoped role). Returns `connection_url` + `note`/`upgrade`. `name` required.              |
 | `create_queue`    | `POST /queue/new` — Provision a NATS JetStream queue (scoped subject namespace). Returns `connection_url` + `note`/`upgrade`. `name` required.                    |
@@ -118,10 +119,10 @@ to reach for this MCP, see <https://instanode.dev/agent.html>.
 | `redeploy`        | `POST /deploy/:id/redeploy` — Rebuild + rolling update an existing deployment. Requires `INSTANODE_TOKEN`.                                                        |
 | `delete_deployment` | `DELETE /deploy/:id` — Tear down a running deployment. Irreversible. Requires `INSTANODE_TOKEN`.                                                                |
 | `claim_resource`  | Helper — turn an `upgrade_jwt` from any `create_*` response into the dashboard claim URL the user should click. No API call. No auth required.                    |
-| `claim_token`     | `POST /api/me/claim` — Programmatic claim: attach an anonymous resource to the authenticated account by its UUID `token`. Requires `INSTANODE_TOKEN`.             |
-| `list_resources`  | `GET /api/me/resources` — List resources on the caller's account. Requires `INSTANODE_TOKEN`.                                                                     |
-| `delete_resource` | `DELETE /api/me/resources/{token}` — Hard-delete a resource you own. Paid tier only. Requires `INSTANODE_TOKEN`.                                                  |
-| `get_api_token`   | `GET /api/me/token` — Mint a fresh 30-day bearer JWT (for rotation). Requires an existing `INSTANODE_TOKEN`.                                                      |
+| `claim_token`     | `POST /claim` — Programmatic claim: attach an anonymous resource to the authenticated account using its `upgrade_jwt` + `email`. No auth required.                |
+| `list_resources`  | `GET /api/v1/resources` — List resources on the caller's account. Requires `INSTANODE_TOKEN`.                                                                     |
+| `delete_resource` | `DELETE /api/v1/resources/{token}` — Hard-delete a resource you own. Paid tier only. Requires `INSTANODE_TOKEN`.                                                  |
+| `get_api_token`   | `POST /api/v1/auth/api-keys` — Mint a fresh bearer Personal Access Token (PAT). Requires an existing user-session `INSTANODE_TOKEN` (PATs cannot mint other PATs — the API returns 403 in that case). |
 
 ### Container deployment (`create_deploy`)
 
@@ -290,7 +291,7 @@ resources, and the account-management tools (`list_resources`,
 3. Set it as `INSTANODE_TOKEN` in the MCP server's `env` block (see examples
    above).
 
-Rotate any time by calling `get_api_token`, which mints a fresh 30-day JWT.
+Rotate any time by calling `get_api_token`, which mints a fresh Personal Access Token via `POST /api/v1/auth/api-keys`. PATs are revocation-based (not time-bound). NOTE: PATs cannot mint other PATs — `get_api_token` requires a user-session token (sign in via the dashboard), not an existing PAT, otherwise the API returns 403.
 
 ## Development
 

package-lock.json

@@ -51,7 +51,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.10.2"
+    "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.InstaNode-dev/mcp",
-  "description": "Provision Postgres databases + webhooks from AI coding agents in one HTTP call.",
+  "description": "Provision Postgres (with pgvector), Redis, MongoDB, NATS JetStream queues, S3-compatible object storage, inbound webhook receivers, and deploy containerized apps from AI coding agents in single HTTP calls.",
   "repository": {
     "url": "https://github.com/InstaNode-dev/mcp",
     "source": "github"

server.json

@@ -128,6 +128,18 @@ export interface DatabaseProvisionResult extends ProvisionResultBase {
   connection_url: string;
 }
 
+export interface VectorProvisionResult extends ProvisionResultBase {
+  /**
+   * postgres:// connection string with the pgvector extension pre-installed
+   * (CREATE EXTENSION vector already ran). Drop-in DATABASE_URL.
+   */
+  connection_url: string;
+  /** Always 'pgvector'. */
+  extension?: string;
+  /** Echo of the requested default embedding dimensions hint (defaults to 1536). */
+  dimensions?: number;
+}
+
 export interface CacheProvisionResult extends ProvisionResultBase {
   /** redis://user:pass@host:port — drop-in REDIS_URL. */
   connection_url: string;
@@ -599,6 +611,22 @@ export class InstantClient {
     return this.request<DatabaseProvisionResult>("POST", "/db/new", { name });
   }
 
+  /**
+   * POST /vector/new — provision a pgvector-enabled Postgres database. `name`
+   * is required client-side for parity with the other create_* tools (the
+   * server allows it to be omitted, but every other endpoint requires it).
+   * Optional `dimensions` is a documentation hint only — pgvector picks
+   * dimensions per column at table-create time.
+   */
+  async createVector(
+    name: string,
+    dimensions?: number
+  ): Promise<VectorProvisionResult> {
+    const body: { name: string; dimensions?: number } = { name };
+    if (typeof dimensions === "number") body.dimensions = dimensions;
+    return this.request<VectorProvisionResult>("POST", "/vector/new", body);
+  }
+
   /** POST /cache/new — provision a Redis cache. `name` is required. */
   async createCache(name: string): Promise<CacheProvisionResult> {
     return this.request<CacheProvisionResult>("POST", "/cache/new", { name });

src/client.ts

@@ -5,6 +5,7 @@
  * Exposes tools to AI coding agents (Claude Code, Cursor, Windsurf, etc.):
  *
  *   create_postgres    — provision an ephemeral Postgres database (with pgvector)
+ *   create_vector      — provision a pgvector-enabled Postgres database (embedding store)
  *   create_cache       — provision a Redis cache (ACL-scoped user + namespace)
  *   create_nosql       — provision a MongoDB database (per-resource user + role)
  *   create_queue       — provision a NATS JetStream queue (publish/subscribe)
@@ -238,6 +239,75 @@ Store the connection_url in an env var (DATABASE_URL); do not hardcode it.`,
   }
 );
 
+// ── Tool: create_vector ───────────────────────────────────────────────────────
+
+server.tool(
+  "create_vector",
+  `Provision a pgvector-enabled Postgres database on instanode.dev (POST /vector/new).
+
+Underlying storage IS Postgres (tier limits mirror Postgres exactly), with the
+pgvector extension already loaded via CREATE EXTENSION vector at provisioning
+time. Use for embedding stores (OpenAI text-embedding-ada-002 / 3-small = 1536
+dims; text-embedding-3-large = 3072). Returns a standard postgres:// connection
+URL — drop in as DATABASE_URL with any pg driver.
+
+Note: create_postgres ALSO ships with pgvector pre-installed today, so this
+tool is functionally equivalent for embedding workloads. Use create_vector when
+the agent wants to make the intent (pgvector / embeddings) explicit, or when
+the API contract evolves and pgvector-only routing diverges from generic
+Postgres provisioning.
+
+The optional 'dimensions' field is a documentation hint only — pgvector lets
+you pick per-column dimensions at table-create time, so the server stores the
+declared default but does not enforce it.
+
+Without INSTANODE_TOKEN: anonymous tier — 10 MB, 2 connections, expires in 24h,
+capped at 5 provisions/day per /24 subnet. The response carries 'note' +
+'upgrade' (claim URL) — surface both verbatim.
+With INSTANODE_TOKEN (paid): hobby/pro/team Postgres limits, permanent.
+
+The 'name' field is required.`,
+  {
+    ...nameArg,
+    dimensions: z
+      .number()
+      .int()
+      .min(1)
+      .max(16000)
+      .optional()
+      .describe(
+        "Optional embedding dimension hint (defaults to 1536 — OpenAI text-embedding-3-small / ada-002). Use 3072 for text-embedding-3-large. Informational only; pgvector enforces dimensions per column at table-create time."
+      ),
+  },
+  async ({ name, dimensions }) => {
+    try {
+      const result = await client.createVector(name, dimensions);
+      const lines = [
+        `pgvector Postgres database provisioned.`,
+        `Token:          ${result.token}`,
+        `Name:           ${result.name ?? name}`,
+        `Tier:           ${result.tier}`,
+        `Connection URL: ${result.connection_url}`,
+        `Extension:      ${result.extension ?? "pgvector"}`,
+        `Dimensions:     ${result.dimensions ?? dimensions ?? 1536}`,
+        ...formatLimits(result.limits),
+      ];
+      appendUpgradeBlock(lines, result);
+      lines.push(
+        ``,
+        `Use directly as DATABASE_URL (add .env to .gitignore):`,
+        `  DATABASE_URL=${result.connection_url}`,
+        ``,
+        `pgvector is ready — no CREATE EXTENSION needed. Pick column dimensions`,
+        `at CREATE TABLE time, e.g. embedding vector(1536).`
+      );
+      return textResult(lines.join("\n"));
+    } catch (err) {
+      return textResult(formatError(err));
+    }
+  }
+);
+
 // ── Tool: create_cache ────────────────────────────────────────────────────────
 
 server.tool(

src/index.ts

@@ -34,7 +34,7 @@ import sys, json
 d = json.loads(sys.stdin.read())
 tools = {t['name'] for t in d['result']['tools']}
 expected = {
-    'create_postgres', 'create_cache', 'create_nosql', 'create_queue',
+    'create_postgres', 'create_vector', 'create_cache', 'create_nosql', 'create_queue',
     'create_storage', 'create_webhook',
     'create_deploy', 'list_deployments', 'get_deployment',
     'redeploy', 'delete_deployment',
@@ -52,7 +52,7 @@ assert not still_there, f'dead tools still registered: {still_there}'
 extra = tools - expected
 assert not extra, f'unexpected tools registered: {extra}'
 " || fail "tools/list missing expected tools or carrying dead ones"
-pass "tools/list returns all 16 tools, no dead ones"
+pass "tools/list returns all 17 tools, no dead ones"
 
 # Test 2b: tools/list — deploy management tools are registered and discoverable.
 # Explicit assertion so the smoke test catches a regression on any single one.
@@ -89,6 +89,34 @@ assert err, f'expected a validation error, got: {d}'
 " || fail "create_postgres with empty name was accepted"
 pass "create_postgres rejects empty name"
 
+# Test 4b: create_vector (B16-F10) is registered and rejects an empty name.
+# Also verifies the optional dimensions field is advertised in the schema.
+BAD_VECTOR='{"jsonrpc":"2.0","id":40,"method":"tools/call","params":{"name":"create_vector","arguments":{"name":""}}}'
+RESP=$(printf "%s\n%s\n" "$INIT" "$BAD_VECTOR" | INSTANODE_API_URL="$BASE_URL" $MCP 2>/dev/null | tail -1)
+echo "$RESP" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+err = d.get('error') or (d.get('result') or {}).get('isError')
+assert err, f'expected a validation error, got: {d}'
+" || fail "create_vector with empty name was accepted"
+pass "create_vector rejects empty name"
+
+# Test 4c: create_vector schema advertises optional dimensions
+RESP=$(printf "%s\n%s\n" "$INIT" "$TOOLS_LIST" | INSTANODE_API_URL="$BASE_URL" $MCP 2>/dev/null | tail -1)
+echo "$RESP" | python3 -c "
+import sys, json
+d = json.loads(sys.stdin.read())
+tools = {t['name']: t for t in d['result']['tools']}
+assert 'create_vector' in tools, f'create_vector not registered'
+schema = tools['create_vector']['inputSchema']
+props = schema.get('properties', {})
+assert 'name' in props, f'create_vector missing name: {list(props.keys())}'
+assert 'dimensions' in props, f'create_vector missing dimensions: {list(props.keys())}'
+desc = tools['create_vector'].get('description', '')
+assert 'pgvector' in desc.lower(), f'create_vector description should mention pgvector'
+" || fail "create_vector schema missing expected properties"
+pass "create_vector schema advertises name + dimensions and mentions pgvector"
+
 # Test 5: claim_resource is a pure helper — works without any API/network access.
 # Accepts a raw JWT and builds the dashboard claim URL.
 CLAIM='{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"claim_resource","arguments":{"upgrade_jwt":"ey.fake.jwt"}}}'

test.sh

@@ -54,6 +54,7 @@ const SERVER_ENTRY = resolve(__dirname, "..", "..", "dist", "index.js");
 /** Every tool the server is contractually required to register. */
 const EXPECTED_TOOLS = [
   "create_postgres",
+  "create_vector",
   "create_cache",
   "create_nosql",
   "create_queue",
@@ -200,7 +201,7 @@ describe("instanode-mcp integration suite", () => {
   // ── Tool registry + schemas ─────────────────────────────────────────────────
 
   describe("tool registry", () => {
-    it("registers exactly the 16 contract tools, no dead ones", async () => {
+    it("registers exactly the 17 contract tools, no dead ones", async () => {
       const { client, close } = await connectClient(mock.url, "none");
       try {
         const { tools } = await client.listTools();

test/integration.test.ts

@@ -331,6 +331,7 @@ async function route(req: IncomingMessage, res: ServerResponse, state: State): P
   // ── create_* provisioning routes ──────────────────────────────────────────
   const provisionRoutes: Record<string, string> = {
     "/db/new": "postgres",
+    "/vector/new": "postgres",
     "/cache/new": "cache",
     "/nosql/new": "nosql",
     "/queue/new": "queue",