@vectros-ai/mcp-server 0.7.0 → 0.9.0

package/dist/cli.js

@@ -675,6 +675,10 @@ var ReadAccessLogResponse;
 })(ReadAccessLogResponse || (ReadAccessLogResponse = {}));
 var RecordRequest;
 ((RecordRequest2) => {
+  RecordRequest2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
   RecordRequest2.IndexMode = {
     Hybrid: "HYBRID",
     Semantic: "SEMANTIC",
@@ -684,6 +688,10 @@ var RecordRequest;
 })(RecordRequest || (RecordRequest = {}));
 var RecordResponse;
 ((RecordResponse2) => {
+  RecordResponse2.Status = {
+    Active: "ACTIVE",
+    Archived: "ARCHIVED"
+  };
   RecordResponse2.IndexStatus = {
     PendingIndex: "PENDING_INDEX",
     Indexed: "INDEXED",
@@ -3158,7 +3166,7 @@ var AuthClient = class {
    *             roleId: "engineering-member",
    *             name: "Engineering Team Member",
    *             scopes: [{
-   *                     allowed_actions: ["read", "write"]
+   *                     allowed_actions: ["records:cru", "search:r"]
    *                 }]
    *         }
    *     })
@@ -3706,7 +3714,7 @@ var AuthClient = class {
    *             roleId: "engineering-member",
    *             name: "Engineering Team Member",
    *             scopes: [{
-   *                     allowed_actions: ["read", "write"]
+   *                     allowed_actions: ["records:cru", "search:r"]
    *                 }]
    *         }
    *     })
@@ -4609,7 +4617,7 @@ var DocumentsClient = class {
     this._options = normalizeClientOptionsWithAuth(options);
   }
   /**
-   * Returns a paginated list of your documents, optionally filtered by folder (`folderId`) and/or owner (`userId`, `orgId`, or `clientId`). The response is a `{data, nextCursor}` envelope; pass `nextCursor` back as `startFrom` to fetch the next page. Requires the `documents:r` scope.
+   * Returns a paginated list of your documents, optionally filtered by folder (`folderId`) and/or owner (`userId`, `orgId`, `clientId`, or `scope`). The response is a `{data, nextCursor}` envelope; pass `nextCursor` back as `startFrom` to fetch the next page. Requires the `documents:r` scope.
    *
    * @param {Vectros.ListDocumentsRequest} request
    * @param {DocumentsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4619,6 +4627,7 @@ var DocumentsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         orgId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         clientId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+   *         scope: "group:eng-team",
    *         folderId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    *         startFrom: "doc_prev123"
    *     })
@@ -4627,11 +4636,12 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__listDocuments(request, requestOptions));
   }
   async __listDocuments(request = {}, requestOptions) {
-    const { userId, orgId, clientId, folderId, startFrom, limit } = request;
+    const { userId, orgId, clientId, scope, folderId, startFrom, limit } = request;
     const _queryParams = {
       userId,
       orgId,
       clientId,
+      scope,
       folderId,
       startFrom,
       limit
@@ -4689,9 +4699,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__ingestDocument(request, requestOptions));
   }
   async __ingestDocument(request, requestOptions) {
-    const { upsert, body: _body } = request;
+    const { upsert, allowClear, body: _body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      allowClear
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -4815,7 +4826,10 @@ var DocumentsClient = class {
     return HttpResponsePromise.fromPromise(this.__updateDocument(request, requestOptions));
   }
   async __updateDocument(request, requestOptions) {
-    const { id, body: _body } = request;
+    const { id, allowClear, body: _body } = request;
+    const _queryParams = {
+      allowClear
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -4830,7 +4844,7 @@ var DocumentsClient = class {
       method: "PUT",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -7566,7 +7580,7 @@ var RecordsClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/records/batch");
   }
   /**
-   * Returns a paginated list of records in your account as a `{data, nextCursor}` page. Supply exactly one of `type`, `folderId`, or `recent=true` to choose the mode: `type` lists all records of a single type; `folderId` lists all records in a folder (any type); and `recent=true` returns the account-wide recently-updated feed across all types, newest first. You may combine `type` with `folderId` to list a single type within a folder. The owner filters (`userId`, `orgId`, `clientId`) further narrow the type and folder modes; the `recent` feed is standalone and ignores all filters. Each token only sees the record types it is scoped to read. Requires the `records:r` scope. By default the response returns the indexed projection of each record; set `includePayload=true` to include full payloads.
+   * Returns a paginated list of records in your account as a `{data, nextCursor}` page. Supply exactly one of `type`, `folderId`, or `recent=true` to choose the mode: `type` lists all records of a single type; `folderId` lists all records in a folder (any type); and `recent=true` returns the account-wide recently-updated feed across all types, newest first. You may combine `type` with `folderId` to list a single type within a folder. The owner filters (`userId`, `orgId`, `clientId`, `scope`) further narrow the type and folder modes; the `recent` feed is standalone and ignores all filters. Each token only sees the record types it is scoped to read. Requires the `records:r` scope. By default the response returns the indexed projection of each record; set `includePayload=true` to include full payloads.
    *
    * @param {Vectros.ListRecordsRequest} request
    * @param {RecordsClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -7578,6 +7592,7 @@ var RecordsClient = class {
    *         userId: "550e8400-e29b-41d4-a716-446655440000",
    *         orgId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    *         clientId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
+   *         scope: "group:eng-team",
    *         startFrom: "550e8400-e29b-41d4-a716-446655440000"
    *     })
    */
@@ -7585,13 +7600,25 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__listRecords(request, requestOptions));
   }
   async __listRecords(request = {}, requestOptions) {
-    const { type: type_, folderId, userId, orgId, clientId, startFrom, limit, includePayload, recent } = request;
+    const {
+      type: type_,
+      folderId,
+      userId,
+      orgId,
+      clientId,
+      scope,
+      startFrom,
+      limit,
+      includePayload,
+      recent
+    } = request;
     const _queryParams = {
       type: type_,
       folderId,
       userId,
       orgId,
       clientId,
+      scope,
       startFrom,
       limit,
       includePayload,
@@ -7656,9 +7683,10 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__createRecord(request, requestOptions));
   }
   async __createRecord(request, requestOptions) {
-    const { upsert, body: _body } = request;
+    const { upsert, allowClear, body: _body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      allowClear
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -7780,7 +7808,10 @@ var RecordsClient = class {
     return HttpResponsePromise.fromPromise(this.__updateRecord(request, requestOptions));
   }
   async __updateRecord(request, requestOptions) {
-    const { id, body: _body } = request;
+    const { id, allowClear, body: _body } = request;
+    const _queryParams = {
+      allowClear
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -7795,7 +7826,7 @@ var RecordsClient = class {
       method: "PUT",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -8782,8 +8813,8 @@ function warnOnSuboptimalKey(key, log) {
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.7.0" : "dev",
-  sdk: true ? "0.33.0" : "dev"
+  mcpServer: true ? "0.9.0" : "dev",
+  sdk: true ? "0.34.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -9022,7 +9053,7 @@ ${detail}${pointer}`
 
 // src/tools/hybrid_search.ts
 var MCP_DEFAULT_LIMIT = 3;
-var MCP_MAX_LIMIT = 10;
+var MCP_MAX_LIMIT = 50;
 var MCP_RESPONSE_CHAR_BUDGET = 24e3;
 var SNIPPET_MAX_CHARS = 160;
 var INTERNAL_METADATA_KEYS = /* @__PURE__ */ new Set(["tenantId", "owner_id", "model_type", "rootFolderId", "folderId"]);
@@ -9056,9 +9087,9 @@ var inputSchema = {
     "Keyword-match precision for the BM25 leg (TEXT/HYBRID modes). OR = any term (broad recall), AND = all terms (higher precision), PHRASE = contiguous phrase. Default: PHRASE (slop 3) in HYBRID, OR in TEXT. (The advanced raw-query COMPLEX mode is intentionally not exposed here.)"
   ),
   limit: import_zod.z.number().int().min(1).max(MCP_MAX_LIMIT).optional().describe(
-    `Max hits to return. MCP-specific cap of ${MCP_MAX_LIMIT} (vs API max of 50) to protect the agent context window. Default 3. Use offset for pagination.`
+    `Max hits per page. Defaults to a low ${MCP_DEFAULT_LIMIT} to protect the agent context window; raise up to ${MCP_MAX_LIMIT} (the most a single search returns) in one call when you can accept the larger result, or page with \`offset\` instead.`
   ),
-  offset: import_zod.z.number().int().min(0).optional().describe("Skip the first N hits \u2014 for pagination."),
+  offset: import_zod.z.number().int().min(0).max(200).optional().describe("Skip the first N hits \u2014 for pagination (0\u2013200)."),
   folderId: import_zod.z.string().optional().describe("Scope to content in this EXACT folder (Vectros folder id)."),
   rootFolderId: import_zod.z.string().optional().describe("Scope to content under this folder AND all its descendants (subtree-root folder id)."),
   // Content narrowing.
@@ -9073,6 +9104,9 @@ var inputSchema = {
   userId: import_zod.z.string().optional().describe("Restrict to content owned by this user (Vectros UUID)."),
   orgId: import_zod.z.string().optional().describe("Restrict to content belonging to this org (Vectros UUID)."),
   clientId: import_zod.z.string().optional().describe("Restrict to content associated with this client (Vectros UUID)."),
+  scope: import_zod.z.string().optional().describe(
+    'Restrict to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `scope=org:<id>`/`scope=client:<id>` are equivalent to the orgId/clientId filters.'
+  ),
   // Date window.
   createdAfter: import_zod.z.string().optional().describe("Restrict to content created at/after this ISO 8601 UTC timestamp."),
   createdBefore: import_zod.z.string().optional().describe("Restrict to content created at/before this ISO 8601 UTC timestamp."),
@@ -9090,7 +9124,7 @@ var inputSchema = {
 var hybridSearch = ({ client, log }) => ({
   name: "hybrid_search",
   title: "Hybrid search",
-  description: `Search the partner tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to 10 results (default 3) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/orgId/clientId), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller's scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents never appear in results \u2014 fetch them by id via document_get, or restore them via document_update. To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). textLegEmpty:true flags that the keyword leg matched nothing (all textScores 0) \u2014 usually a too-long PHRASE query; retry with textMode:"OR".`,
+  description: "Search your tenant's indexed content (documents + structured records) using hybrid BM25 + dense ranking. Returns up to `limit` results (default 3, max 50 \u2014 raise it in one call when you can accept the larger result) with citations and surrounding context for grounding follow-up reasoning. Narrow with contentTypes/typeName/filters, ownership (userId/orgId/clientId), folder scope, a created date window, keyword precision (textMode OR/AND/PHRASE), relevance floors (minSimilarity/minTextRelevance), uniqueDocuments, and requireComplete (fail closed on a degraded backend). Tenant-isolated; the caller's scoped key fully constrains which content is visible. ARCHIVED (soft-retracted) documents never appear in results \u2014 fetch them by id via document_get, or restore them via document_update. To stay within the agent context window each hit returns its matched chunkText + a short snippet by default; set includeContext:true for the broader surrounding passage. If the whole result would be too large it is truncated to the top hits (truncated:true). totalResults is the full matching pool and hasMore:true means results remain past this page \u2014 raise limit or advance offset to fetch them. textLegEmpty:true flags that the keyword leg matched nothing (all textScores 0) \u2014 usually a too-long PHRASE query; retry with textMode:\"OR\".",
   inputSchema,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT;
@@ -9110,6 +9144,7 @@ var hybridSearch = ({ client, log }) => ({
         userId: args.userId,
         orgId: args.orgId,
         clientId: args.clientId,
+        scope: args.scope,
         createdAfter: args.createdAfter,
         createdBefore: args.createdBefore,
         minSimilarity: args.minSimilarity,
@@ -9136,6 +9171,12 @@ var hybridSearch = ({ client, log }) => ({
         envelope.returnedResults = shaped.length;
         text = JSON.stringify(envelope, null, 2);
       }
+      const offset = args.offset ?? 0;
+      const totalResults = result.totalResults;
+      if (typeof totalResults === "number" && offset + shaped.length < totalResults) {
+        envelope.hasMore = true;
+        text = JSON.stringify(envelope, null, 2);
+      }
       log.debug(
         { tool: "hybrid_search", mode, limit, returned: shaped.length, textLegEmpty },
         "hybrid_search ok"
@@ -9171,7 +9212,7 @@ async function drainPages(fetchPage) {
 
 // src/tools/record_query.ts
 var MCP_DEFAULT_LIMIT2 = 3;
-var MCP_MAX_LIMIT2 = 10;
+var MCP_MAX_LIMIT2 = 100;
 var inputSchema2 = {
   type: import_zod2.z.string().min(1, "type (record type) is required").describe('Record type / schema name (e.g. "patient", "clinical_note").'),
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
@@ -9189,14 +9230,18 @@ var inputSchema2 = {
   userId: import_zod2.z.string().optional().describe("List mode: scope to records owned by this user."),
   orgId: import_zod2.z.string().optional().describe("List mode: scope to records owned by this org."),
   clientId: import_zod2.z.string().optional().describe("List mode: scope to records associated with this client."),
+  scope: import_zod2.z.string().optional().describe(
+    'List mode: filter to records carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `scope=org:<id>`/`scope=client:<id>` are equivalent to the orgId/clientId filters.'
+  ),
+  startFrom: import_zod2.z.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next. Works in both list and lookup mode."),
   limit: import_zod2.z.number().int().min(1).max(MCP_MAX_LIMIT2).optional().describe(
-    `Max records to return. MCP-specific cap of ${MCP_MAX_LIMIT2} (vs API max of 100) to protect the agent context window. Default 3.`
+    `Max records per page. Defaults to a low ${MCP_DEFAULT_LIMIT2} to protect the agent context window; raise up to ${MCP_MAX_LIMIT2} (the records API max) in one call when you can accept the larger payload, or page with \`startFrom\` instead.`
   )
 };
 var recordQuery = ({ client, log }) => ({
   name: "record_query",
   title: "Record query (list or lookup)",
-  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields too.\n  \u2022 List by type: omit `field`; optionally filter by `userId`/`orgId`/`clientId`.\nReturns up to 10 records (default 3). Mode is auto-detected from the arguments present.",
+  description: "Query structured records of a given type. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields too.\n  \u2022 List by type: omit `field`; optionally filter by `userId`/`orgId`/`clientId`.\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` records (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. Mode is auto-detected from the arguments present.",
   inputSchema: inputSchema2,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT2;
@@ -9206,8 +9251,9 @@ var recordQuery = ({ client, log }) => ({
     const from = args.from;
     const to = args.to;
     const prefix = args.prefix;
+    const startFrom = args.startFrom;
     try {
-      let records;
+      let page;
       if (field) {
         const hasEquality = value !== void 0;
         const hasRange = from !== void 0 || to !== void 0;
@@ -9230,7 +9276,7 @@ var recordQuery = ({ client, log }) => ({
         if (hasRange && !(from !== void 0 && to !== void 0)) {
           return toolError("record_query", new Error("range lookup requires both 'from' and 'to'."));
         }
-        const page = await client.records.lookupRecordsByBody({
+        page = await client.records.lookupRecordsByBody({
           type,
           field,
           value,
@@ -9238,29 +9284,32 @@ var recordQuery = ({ client, log }) => ({
           to,
           prefix,
           order: args.order,
+          startFrom,
           limit
         });
-        records = pageItems(page);
         log.debug(
-          { tool: "record_query", mode: "lookup", type, field, returned: records.length },
+          { tool: "record_query", mode: "lookup", type, field, returned: pageItems(page).length },
           "record_query lookup ok"
         );
       } else {
-        const page = await client.records.listRecords({
+        page = await client.records.listRecords({
           type,
           userId: args.userId,
           orgId: args.orgId,
           clientId: args.clientId,
+          scope: args.scope,
+          startFrom,
           limit
         });
-        records = pageItems(page);
         log.debug(
-          { tool: "record_query", mode: "list", type, limit, returned: records.length },
+          { tool: "record_query", mode: "list", type, limit, returned: pageItems(page).length },
           "record_query list ok"
         );
       }
+      const records = pageItems(page);
+      const nextCursor = page.nextCursor ?? null;
       return {
-        content: [{ type: "text", text: JSON.stringify(records, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify({ data: records, nextCursor }, null, 2) }]
       };
     } catch (err) {
       log.warn({ tool: "record_query", err: String(err) }, "record_query failed");
@@ -9383,7 +9432,10 @@ var inputSchema4 = {
   folderId: import_zod4.z.string().optional().describe("Group this record into a folder."),
   userId: import_zod4.z.string().optional().describe("Owning user id."),
   orgId: import_zod4.z.string().optional().describe("Owning organization id."),
-  clientId: import_zod4.z.string().optional().describe("Associated client id.")
+  clientId: import_zod4.z.string().optional().describe("Associated client id."),
+  scopes: import_zod4.z.array(import_zod4.z.string()).optional().describe(
+    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). This is the record\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE record owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default. `org:`/`client:` entries are equivalent to the orgId/clientId fields.'
+  )
 };
 var recordCreate = ({ client, log }) => ({
   name: "record_create",
@@ -9403,7 +9455,8 @@ var recordCreate = ({ client, log }) => ({
           folderId: args.folderId,
           userId: args.userId,
           orgId: args.orgId,
-          clientId: args.clientId
+          clientId: args.clientId,
+          scopes: args.scopes
         }
       });
       log.debug({ tool: "record_create", type, id: created.id }, "record_create ok");
@@ -9488,24 +9541,29 @@ var record_delete_default = recordDelete;
 // src/tools/rag_ask.ts
 var import_zod7 = require("zod");
 var SEARCH_MCP_DEFAULT_LIMIT = 5;
-var SEARCH_MCP_MAX_LIMIT = 10;
+var SEARCH_MCP_MAX_LIMIT = 50;
 var inputSchema7 = {
   query: import_zod7.z.string().min(1, "query must be non-empty").describe("Question to ground against retrieved content."),
   instructions: import_zod7.z.string().optional().describe(
     'System prompt that overrides the default for the generation step \u2014 e.g. "answer only from the provided context, cite sources, be concise". Default: a generic answer-from-context instruction.'
   ),
   model: import_zod7.z.string().optional().describe(
-    "Inference model alias (e.g. claude-haiku-4-5, claude-sonnet-4-6, claude-opus-4-8). Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach."
+    "Inference model alias (e.g. claude-haiku-4-5, claude-sonnet-5, claude-opus-4-8). Default = tier-appropriate Haiku. See GET /v1/models for the catalog the calling key can reach."
   ),
   search: import_zod7.z.object({
     mode: import_zod7.z.enum(["HYBRID", "TEXT", "SEMANTIC"]).optional().describe("Retrieval mode. Default HYBRID."),
-    limit: import_zod7.z.number().int().min(1).max(SEARCH_MCP_MAX_LIMIT).optional().describe(`Passages to retrieve before generating. Default ${SEARCH_MCP_DEFAULT_LIMIT}, max ${SEARCH_MCP_MAX_LIMIT}.`),
+    limit: import_zod7.z.number().int().min(1).max(SEARCH_MCP_MAX_LIMIT).optional().describe(
+      `Passages to retrieve before generating (the grounding-corpus size). Default ${SEARCH_MCP_DEFAULT_LIMIT}; raise up to ${SEARCH_MCP_MAX_LIMIT} (the RAG search API max) for a broader corpus when the extra grounding is worth the larger prompt.`
+    ),
     // Retrieval scoping — parity with hybrid_search so an agent can ground the
     // answer on a specific owner / folder / type / metadata subset, not just the
     // whole-tenant corpus.
     userId: import_zod7.z.string().optional().describe("Restrict retrieval to content owned by this user (Vectros UUID)."),
     orgId: import_zod7.z.string().optional().describe("Restrict retrieval to content owned by this org (Vectros UUID)."),
     clientId: import_zod7.z.string().optional().describe("Restrict retrieval to content tagged with this client (Vectros UUID)."),
+    scope: import_zod7.z.string().optional().describe(
+      'Restrict retrieval to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `scope=org:<id>`/`scope=client:<id>` are equivalent to the orgId/clientId filters.'
+    ),
     folderId: import_zod7.z.string().optional().describe("Restrict retrieval to this exact folder."),
     rootFolderId: import_zod7.z.string().optional().describe("Restrict retrieval to this folder and all its descendants."),
     typeName: import_zod7.z.string().optional().describe("Restrict record retrieval to this schema type."),
@@ -9523,7 +9581,7 @@ var inputSchema7 = {
 var ragAsk = ({ client, log }) => ({
   name: "rag_ask",
   title: "RAG ask (corpus-wide)",
-  description: "Ask a question grounded against the partner tenant's indexed content. Vectros performs a hybrid search, injects the top-K passages into the prompt, and streams a model answer back. Scope retrieval with `search` (ownership, folder, type, metadata filters, date window) to ground on a subset \u2014 e.g. one patient or one folder \u2014 and steer generation with `instructions` / `temperature`. The full answer is returned as a single response; progress notifications keep the call alive during the 30-45s generation window. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
+  description: "Ask a question grounded against your tenant's indexed content. Vectros performs a hybrid search, injects the top-K passages into the prompt, and streams a model answer back. Scope retrieval with `search` (ownership, folder, type, metadata filters, date window) to ground on a subset \u2014 e.g. one patient or one folder \u2014 and steer generation with `instructions` / `temperature`. The full answer is returned as a single response; progress notifications keep the call alive during the 30-45s generation window. Inference runs in-perimeter against AWS Bedrock \u2014 PHI never leaves the BAA boundary.",
   inputSchema: inputSchema7,
   handler: async (args, extra) => {
     try {
@@ -9534,6 +9592,7 @@ var ragAsk = ({ client, log }) => ({
         userId: searchArg.userId,
         orgId: searchArg.orgId,
         clientId: searchArg.clientId,
+        scope: searchArg.scope,
         folderId: searchArg.folderId,
         rootFolderId: searchArg.rootFolderId,
         typeName: searchArg.typeName,
@@ -9691,7 +9750,7 @@ var inputSchema9 = {
 var listSchemas = ({ client, log }) => ({
   name: "list_schemas",
   title: "List record schemas",
-  description: 'List the structured-record schema catalog for the partner tenant. Each schema describes a record type (e.g. "patient", "clinical_note") \u2014 its fields, lookup-indexed fields, and capabilities. Use this to discover what record types exist before calling `record_query`. Filter with `surface` (record/document/user/org/client \u2014 e.g. only document types), `recordType` (resolve one schema by its type name), or `userId`/`orgId`; default returns everything the credential can see.',
+  description: 'List the structured-record schema catalog for your tenant. Each schema describes a record type (e.g. "patient", "clinical_note") \u2014 its fields, lookup-indexed fields, and capabilities. Use this to discover what record types exist before calling `record_query`. Filter with `surface` (record/document/user/org/client \u2014 e.g. only document types), `recordType` (resolve one schema by its type name), or `userId`/`orgId`; default returns everything the credential can see.',
   inputSchema: inputSchema9,
   handler: async (args) => {
     const userId = args.userId;
@@ -9813,7 +9872,7 @@ var document_get_default = documentGet;
 // src/tools/document_query.ts
 var import_zod11 = require("zod");
 var MCP_DEFAULT_LIMIT3 = 3;
-var MCP_MAX_LIMIT3 = 10;
+var MCP_MAX_LIMIT3 = 100;
 var inputSchema11 = {
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
   field: import_zod11.z.string().optional().describe("Lookup mode: name of the lookup-indexed field to query by."),
@@ -9830,14 +9889,18 @@ var inputSchema11 = {
   userId: import_zod11.z.string().optional().describe("List mode: scope to documents owned by this user."),
   orgId: import_zod11.z.string().optional().describe("List mode: scope to documents belonging to this org."),
   clientId: import_zod11.z.string().optional().describe("List mode: scope to documents associated with this client."),
+  scope: import_zod11.z.string().optional().describe(
+    'List mode: filter to documents carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `scope=org:<id>`/`scope=client:<id>` are equivalent to the orgId/clientId filters.'
+  ),
+  startFrom: import_zod11.z.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next. Works in both list and lookup mode."),
   limit: import_zod11.z.number().int().min(1).max(MCP_MAX_LIMIT3).optional().describe(
-    `Max documents to return. MCP-specific cap of ${MCP_MAX_LIMIT3} (vs API max of 100) to protect the agent context window. Default 3.`
+    `Max documents per page. Defaults to a low ${MCP_DEFAULT_LIMIT3} to protect the agent context window; raise up to ${MCP_MAX_LIMIT3} (the documents API max) in one call when you can accept the larger payload, or page with \`startFrom\` instead.`
   )
 };
 var documentQuery = ({ client, log }) => ({
   name: "document_query",
   title: "Document query (list or lookup)",
-  description: "Query document metadata. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields (equality only there); range/prefix need a range-enabled field.\n  \u2022 List: omit `field`; optionally filter by `folderId`/`userId`/`orgId`/`clientId`.\nReturns up to 10 documents (default 3) as a bare array. Mode is auto-detected. Use document_get for the full text/download URL of one document.",
+  description: "Query document metadata. Two modes:\n  \u2022 Lookup on a lookup-indexed field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Works on sensitive fields (equality only there); range/prefix need a range-enabled field.\n  \u2022 List: omit `field`; optionally filter by `folderId`/`userId`/`orgId`/`clientId`/`scope`.\nReturns a `{ data, nextCursor }` page: `data` holds up to `limit` documents (default 3, max 100 \u2014 raise it in one call when you can accept the payload), and a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page. Mode is auto-detected. Use document_get for the full text/download URL of one document.",
   inputSchema: inputSchema11,
   handler: async (args) => {
     const limit = args.limit ?? MCP_DEFAULT_LIMIT3;
@@ -9847,8 +9910,9 @@ var documentQuery = ({ client, log }) => ({
     const to = args.to;
     const prefix = args.prefix;
     const type = args.type;
+    const startFrom = args.startFrom;
     try {
-      let documents;
+      let page;
       if (field) {
         const hasEquality = value !== void 0;
         const hasRange = from !== void 0 || to !== void 0;
@@ -9877,7 +9941,7 @@ var documentQuery = ({ client, log }) => ({
             new Error("lookup requires 'type' (the document's bound schema type) alongside 'field'.")
           );
         }
-        const page = await client.documents.lookupDocumentsByBody({
+        page = await client.documents.lookupDocumentsByBody({
           type,
           field,
           value,
@@ -9885,28 +9949,31 @@ var documentQuery = ({ client, log }) => ({
           to,
           prefix,
           order: args.order,
+          startFrom,
           limit
         });
-        documents = pageItems(page);
         log.debug(
-          { tool: "document_query", mode: "lookup", type, field, returned: documents.length },
+          { tool: "document_query", mode: "lookup", type, field, returned: pageItems(page).length },
           "document_query lookup ok"
         );
       } else {
-        const page = await client.documents.listDocuments({
+        page = await client.documents.listDocuments({
           folderId: args.folderId,
           userId: args.userId,
           orgId: args.orgId,
           clientId: args.clientId,
+          scope: args.scope,
+          startFrom,
           limit
         });
-        documents = pageItems(page);
         log.debug(
-          { tool: "document_query", mode: "list", limit, returned: documents.length },
+          { tool: "document_query", mode: "list", limit, returned: pageItems(page).length },
           "document_query list ok"
         );
       }
-      return { content: [{ type: "text", text: JSON.stringify(documents, null, 2) }] };
+      const documents = pageItems(page);
+      const nextCursor = page.nextCursor ?? null;
+      return { content: [{ type: "text", text: JSON.stringify({ data: documents, nextCursor }, null, 2) }] };
     } catch (err) {
       log.warn({ tool: "document_query", err: String(err) }, "document_query failed");
       return toolError("document_query", err);
@@ -10015,7 +10082,7 @@ var document_delete_default = documentDelete;
 // src/tools/folder_query.ts
 var import_zod14 = require("zod");
 var MCP_DEFAULT_LIMIT4 = 10;
-var MCP_MAX_LIMIT4 = 50;
+var MCP_MAX_LIMIT4 = 100;
 var inputSchema14 = {
   id: import_zod14.z.string().optional().describe("Get mode: fetch this single folder by id."),
   parentId: import_zod14.z.string().optional().describe("List mode: direct children of this folder (tree navigation). Omit for a flat tenant list."),
@@ -10023,12 +10090,14 @@ var inputSchema14 = {
   orgId: import_zod14.z.string().optional().describe("List mode: scope to folders belonging to this org."),
   clientId: import_zod14.z.string().optional().describe("List mode: scope to folders associated with this client."),
   startFrom: import_zod14.z.string().optional().describe("List mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
-  limit: import_zod14.z.number().int().min(1).max(MCP_MAX_LIMIT4).optional().describe(`List mode: max folders to return. MCP cap of ${MCP_MAX_LIMIT4} (vs API 100). Default 10.`)
+  limit: import_zod14.z.number().int().min(1).max(MCP_MAX_LIMIT4).optional().describe(
+    `List mode: max folders per page. Default 10; raise up to ${MCP_MAX_LIMIT4} (the folders API max) in one call when you can accept the larger page, or page with \`startFrom\`.`
+  )
 };
 var folderQuery = ({ client, log }) => ({
   name: "folder_query",
   title: "Folder query (list or get)",
-  description: "Read folders. Two modes:\n  \u2022 Get: pass `id` \u2192 returns the single folder.\n  \u2022 List: omit `id`; pass `parentId` for a folder's direct children (tree navigation) or omit for a flat tenant list. Optionally filter by `userId`/`orgId`/`clientId`.\nList mode returns `{ data, nextCursor }` (default 10, max 50 per page); pass `nextCursor` back as `startFrom` to page through all folders. Get mode returns the single folder object.",
+  description: "Read folders. Two modes:\n  \u2022 Get: pass `id` \u2192 returns the single folder.\n  \u2022 List: omit `id`; pass `parentId` for a folder's direct children (tree navigation) or omit for a flat tenant list. Optionally filter by `userId`/`orgId`/`clientId`.\nList mode returns `{ data, nextCursor }` (default 10, max 100 per page \u2014 raise it in one call when you can accept the larger page); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom` to page through all folders. Get mode returns the single folder object.",
   inputSchema: inputSchema14,
   handler: async (args) => {
     const id = args.id;
@@ -10068,7 +10137,10 @@ var inputSchema15 = {
   slug: import_zod15.z.string().optional().describe("Optional stable slug (sibling-unique; idempotency key). Lowercase letters/digits/hyphens. Derived from name when omitted."),
   userId: import_zod15.z.string().optional().describe("Owning user (Vectros UUID)."),
   orgId: import_zod15.z.string().optional().describe("Owning org (Vectros UUID)."),
-  clientId: import_zod15.z.string().optional().describe("Associated client (Vectros UUID).")
+  clientId: import_zod15.z.string().optional().describe("Associated client (Vectros UUID)."),
+  scopes: import_zod15.z.array(import_zod15.z.string()).optional().describe(
+    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). This is the folder\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE folder owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default. `org:`/`client:` entries are equivalent to the orgId/clientId fields.'
+  )
 };
 var folderCreate = ({ client, log }) => ({
   name: "folder_create",
@@ -10085,7 +10157,8 @@ var folderCreate = ({ client, log }) => ({
           slug: args.slug,
           userId: args.userId,
           orgId: args.orgId,
-          clientId: args.clientId
+          clientId: args.clientId,
+          scopes: args.scopes
         }
       });
       log.debug({ tool: "folder_create", id: folder.id, name: folder.name }, "folder_create ok");
@@ -10297,7 +10370,10 @@ var inputSchema19 = {
   folderId: import_zod18.z.string().optional().describe("Optional folder to ingest into. Default: tenant root."),
   userId: import_zod18.z.string().optional().describe("Owning user ID. Optional."),
   orgId: import_zod18.z.string().optional().describe("Owning org ID. Optional."),
-  clientId: import_zod18.z.string().optional().describe("Owning client ID. Optional.")
+  clientId: import_zod18.z.string().optional().describe("Owning client ID. Optional."),
+  scopes: import_zod18.z.array(import_zod18.z.string()).optional().describe(
+    "TEXT MODE ONLY. Scope ownership as `namespace:value` entries, at most 2 (e.g. [\"org:<uuid>\", \"group:eng-team\"]). This is the document's COMPLETE scope declaration and values must come from the credential's own identity. An empty array `[]` creates a PRIVATE document owned by the calling user alone. Omit to stamp the credential's full identity \u2014 the default. `org:`/`client:` entries are equivalent to the orgId/clientId fields. Rejected with `filePath` (file uploads do not accept a scope declaration): a file-uploaded document is stamped with the credential's full identity."
+  )
 };
 var documentIngest = ({ client, log, transport, ingestRoot }) => ({
   name: "document_ingest",
@@ -10331,6 +10407,14 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
         )
       );
     }
+    if (filePath && args.scopes !== void 0) {
+      return toolError(
+        "document_ingest",
+        new Error(
+          "`scopes` is not supported with `filePath` \u2014 file uploads do not accept a scope declaration, and silently ignoring it could make an intended-private document team-visible. Use `text` mode to declare scopes, or omit `scopes` (the upload is stamped with the credential's full identity)."
+        )
+      );
+    }
     const common = {
       folderId: args.folderId,
       payload: args.payload,
@@ -10348,6 +10432,9 @@ var documentIngest = ({ client, log, transport, ingestRoot }) => ({
             title,
             text,
             indexMode,
+            // Scope ownership is a TEXT-mode contract only (the upload-init
+            // endpoint has no scopes field — see the gate above).
+            scopes: args.scopes,
             ...common
           }
         });
@@ -10440,7 +10527,7 @@ var document_ingest_default = documentIngest;
 // src/tools/lookup_principal.ts
 var import_zod19 = require("zod");
 var MCP_DEFAULT_LIMIT5 = 10;
-var MCP_MAX_LIMIT5 = 50;
+var MCP_MAX_LIMIT5 = 100;
 var inputSchema20 = {
   kind: import_zod19.z.enum(["user", "org", "client"]).describe("Which principal to look up: a user, an organization, or a client."),
   externalId: import_zod19.z.string().optional().describe(
@@ -10454,12 +10541,15 @@ var inputSchema20 = {
   to: import_zod19.z.string().optional().describe("Lookup mode (range): inclusive upper bound; requires `from`."),
   prefix: import_zod19.z.string().optional().describe("Lookup mode (prefix): match values starting with this. Range-enabled string fields only."),
   order: import_zod19.z.enum(["asc", "desc"]).optional().describe("Lookup mode: sort direction by the looked-up field. `asc` (default) or `desc`."),
-  limit: import_zod19.z.number().int().min(1).max(MCP_MAX_LIMIT5).optional().describe(`Max principals to return. MCP cap of ${MCP_MAX_LIMIT5} (vs API 100). Default ${MCP_DEFAULT_LIMIT5}.`)
+  startFrom: import_zod19.z.string().optional().describe("Lookup mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
+  limit: import_zod19.z.number().int().min(1).max(MCP_MAX_LIMIT5).optional().describe(
+    `Max principals per page. Defaults to ${MCP_DEFAULT_LIMIT5}; raise up to ${MCP_MAX_LIMIT5} (the principals API max) in one call when you can accept the payload, or page with \`startFrom\`.`
+  )
 };
 var lookupPrincipal = ({ client, log }) => ({
   name: "lookup_principal",
   title: "Look up a user / org / client identity",
-  description: "Resolve a user, org, or client identity. Two modes:\n  \u2022 Resolve by your own id: pass `externalId` \u2192 the matching principal incl. its Vectros UUID (the id the ownership filters on record_query / hybrid_search / rag_ask expect).\n  \u2022 Lookup by a schema field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Sensitive-field-safe. (If both `externalId` and a `field` lookup are given, `externalId` wins.) Returns up to 50 principals (default 10) as a bare array. Read-only \u2014 does not create or modify identities.",
+  description: "Resolve a user, org, or client identity. Two modes:\n  \u2022 Resolve by your own id: pass `externalId` \u2192 the matching principal incl. its Vectros UUID (the id the ownership filters on record_query / hybrid_search / rag_ask expect).\n  \u2022 Lookup by a schema field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Sensitive-field-safe. (If both `externalId` and a `field` lookup are given, `externalId` wins.) Returns a `{ data, nextCursor }` page (default 10, max 100 \u2014 raise it in one call when you can accept the payload); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom`. Read-only \u2014 does not create or modify identities.",
   inputSchema: inputSchema20,
   handler: async (args) => {
     const kind = args.kind;
@@ -10472,6 +10562,7 @@ var lookupPrincipal = ({ client, log }) => ({
     const to = args.to;
     const prefix = args.prefix;
     const order = args.order;
+    const startFrom = args.startFrom;
     try {
       let page;
       if (externalId !== void 0) {
@@ -10509,7 +10600,7 @@ var lookupPrincipal = ({ client, log }) => ({
             new Error("lookup requires 'type' (the identity schema's record type) alongside 'field'.")
           );
         }
-        const req = { type, field, value, from, to, prefix, order, limit };
+        const req = { type, field, value, from, to, prefix, order, startFrom, limit };
         if (kind === "user") {
           page = await client.identity.lookupUsers(req);
         } else if (kind === "org") {
@@ -10525,7 +10616,8 @@ var lookupPrincipal = ({ client, log }) => ({
         );
       }
       const principals = pageItems(page);
-      return { content: [{ type: "text", text: JSON.stringify(principals, null, 2) }] };
+      const nextCursor = page.nextCursor ?? null;
+      return { content: [{ type: "text", text: JSON.stringify({ data: principals, nextCursor }, null, 2) }] };
     } catch (err) {
       log.warn({ tool: "lookup_principal", kind, err: String(err) }, "lookup_principal failed");
       return toolError("lookup_principal", err);