@manifest-network/manifest-mcp-browser 0.1.0 → 0.1.5

package/src/queries/gov.ts

@@ -1,46 +1,54 @@
 import { ManifestQueryClient } from '../client.js';
-import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
-import { parseBigInt, parseInt, defaultPagination } from './utils.js';
+import {
+  ProposalResult, ProposalsResult, VoteResult, VotesResult,
+  DepositResult, DepositsResult, TallyResult, GovParamsResult
+} from '../types.js';
+import { parseBigInt, parseInteger, requireArgs, extractPaginationArgs } from './utils.js';
+import { throwUnsupportedSubcommand } from '../modules.js';
+
+/** Gov query result union type */
+type GovQueryResult =
+  | ProposalResult
+  | ProposalsResult
+  | VoteResult
+  | VotesResult
+  | DepositResult
+  | DepositsResult
+  | TallyResult
+  | GovParamsResult;
 
 /**
  * Route gov query to manifestjs query client
+ *
+ * Paginated queries support --limit flag (default: 100, max: 1000)
  */
 export async function routeGovQuery(
   queryClient: ManifestQueryClient,
   subcommand: string,
   args: string[]
-): Promise<Record<string, unknown>> {
+): Promise<GovQueryResult> {
   const gov = queryClient.cosmos.gov.v1;
 
   switch (subcommand) {
     case 'proposal': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'proposal requires proposal-id argument'
-        );
-      }
+      requireArgs(args, 1, ['proposal-id'], 'gov proposal');
       const proposalId = parseBigInt(args[0], 'proposal-id');
       const result = await gov.proposal({ proposalId });
       return { proposal: result.proposal };
     }
 
     case 'proposals': {
-      // Parse optional status filter
-      const proposalStatus = args[0] ? parseInt(args[0], 'status') : 0;
-      const voter = args[1] || '';
-      const depositor = args[2] || '';
-      const result = await gov.proposals({ proposalStatus, voter, depositor, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'gov proposals');
+      // All optional: status filter, voter, depositor
+      const proposalStatus = remainingArgs[0] ? parseInteger(remainingArgs[0], 'status') : 0;
+      const voter = remainingArgs[1] || '';
+      const depositor = remainingArgs[2] || '';
+      const result = await gov.proposals({ proposalStatus, voter, depositor, pagination });
       return { proposals: result.proposals, pagination: result.pagination };
     }
 
     case 'vote': {
-      if (args.length < 2) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'vote requires proposal-id and voter-address arguments'
-        );
-      }
+      requireArgs(args, 2, ['proposal-id', 'voter-address'], 'gov vote');
       const proposalId = parseBigInt(args[0], 'proposal-id');
       const voter = args[1];
       const result = await gov.vote({ proposalId, voter });
@@ -48,24 +56,15 @@ export async function routeGovQuery(
     }
 
     case 'votes': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'votes requires proposal-id argument'
-        );
-      }
-      const proposalId = parseBigInt(args[0], 'proposal-id');
-      const result = await gov.votes({ proposalId, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'gov votes');
+      requireArgs(remainingArgs, 1, ['proposal-id'], 'gov votes');
+      const proposalId = parseBigInt(remainingArgs[0], 'proposal-id');
+      const result = await gov.votes({ proposalId, pagination });
       return { votes: result.votes, pagination: result.pagination };
     }
 
     case 'deposit': {
-      if (args.length < 2) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'deposit requires proposal-id and depositor-address arguments'
-        );
-      }
+      requireArgs(args, 2, ['proposal-id', 'depositor-address'], 'gov deposit');
       const proposalId = parseBigInt(args[0], 'proposal-id');
       const depositor = args[1];
       const result = await gov.deposit({ proposalId, depositor });
@@ -73,30 +72,22 @@ export async function routeGovQuery(
     }
 
     case 'deposits': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'deposits requires proposal-id argument'
-        );
-      }
-      const proposalId = parseBigInt(args[0], 'proposal-id');
-      const result = await gov.deposits({ proposalId, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'gov deposits');
+      requireArgs(remainingArgs, 1, ['proposal-id'], 'gov deposits');
+      const proposalId = parseBigInt(remainingArgs[0], 'proposal-id');
+      const result = await gov.deposits({ proposalId, pagination });
       return { deposits: result.deposits, pagination: result.pagination };
     }
 
     case 'tally': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'tally requires proposal-id argument'
-        );
-      }
+      requireArgs(args, 1, ['proposal-id'], 'gov tally');
       const proposalId = parseBigInt(args[0], 'proposal-id');
       const result = await gov.tallyResult({ proposalId });
       return { tally: result.tally };
     }
 
     case 'params': {
+      // Optional: params type (defaults to 'tallying')
       const paramsType = args[0] || 'tallying';
       const result = await gov.params({ paramsType });
       return {
@@ -108,21 +99,6 @@ export async function routeGovQuery(
     }
 
     default:
-      throw new ManifestMCPError(
-        ManifestMCPErrorCode.UNSUPPORTED_QUERY,
-        `Unsupported gov query subcommand: ${subcommand}`,
-        {
-          availableSubcommands: [
-            'proposal',
-            'proposals',
-            'vote',
-            'votes',
-            'deposit',
-            'deposits',
-            'tally',
-            'params',
-          ],
-        }
-      );
+      throwUnsupportedSubcommand('query', 'gov', subcommand);
   }
 }

package/src/queries/index.ts

@@ -1,4 +1,13 @@
-export { parseBigInt, parseInt, defaultPagination, DEFAULT_PAGE_LIMIT } from './utils.js';
+export {
+  parseBigInt,
+  parseInteger,
+  createPagination,
+  extractPaginationArgs,
+  DEFAULT_PAGE_LIMIT,
+  MAX_PAGE_LIMIT,
+  defaultPagination,
+} from './utils.js';
+export type { PaginationConfig } from './utils.js';
 export { routeBankQuery } from './bank.js';
 export { routeStakingQuery } from './staking.js';
 export { routeDistributionQuery } from './distribution.js';

package/src/queries/staking.ts

@@ -1,25 +1,40 @@
 import { ManifestQueryClient } from '../client.js';
-import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
-import { parseBigInt, defaultPagination } from './utils.js';
+import {
+  DelegationResult, DelegationsResult, UnbondingDelegationResult, UnbondingDelegationsResult,
+  RedelegationsResult, ValidatorResult, ValidatorsResult, StakingPoolResult,
+  StakingParamsResult, HistoricalInfoResult
+} from '../types.js';
+import { parseBigInt, requireArgs, extractPaginationArgs } from './utils.js';
+import { throwUnsupportedSubcommand } from '../modules.js';
+
+/** Staking query result union type */
+type StakingQueryResult =
+  | DelegationResult
+  | DelegationsResult
+  | UnbondingDelegationResult
+  | UnbondingDelegationsResult
+  | RedelegationsResult
+  | ValidatorResult
+  | ValidatorsResult
+  | StakingPoolResult
+  | StakingParamsResult
+  | HistoricalInfoResult;
 
 /**
  * Route staking query to manifestjs query client
+ *
+ * Paginated queries support --limit flag (default: 100, max: 1000)
  */
 export async function routeStakingQuery(
   queryClient: ManifestQueryClient,
   subcommand: string,
   args: string[]
-): Promise<Record<string, unknown>> {
+): Promise<StakingQueryResult> {
   const staking = queryClient.cosmos.staking.v1beta1;
 
   switch (subcommand) {
     case 'delegation': {
-      if (args.length < 2) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'delegation requires delegator-address and validator-address arguments'
-        );
-      }
+      requireArgs(args, 2, ['delegator-address', 'validator-address'], 'staking delegation');
       const [delegatorAddr, validatorAddr] = args;
       const result = await staking.delegation({
         delegatorAddr,
@@ -29,14 +44,10 @@ export async function routeStakingQuery(
     }
 
     case 'delegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'delegations requires delegator-address argument'
-        );
-      }
-      const [delegatorAddr] = args;
-      const result = await staking.delegatorDelegations({ delegatorAddr, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking delegations');
+      requireArgs(remainingArgs, 1, ['delegator-address'], 'staking delegations');
+      const [delegatorAddr] = remainingArgs;
+      const result = await staking.delegatorDelegations({ delegatorAddr, pagination });
       return {
         delegationResponses: result.delegationResponses,
         pagination: result.pagination,
@@ -44,12 +55,7 @@ export async function routeStakingQuery(
     }
 
     case 'unbonding-delegation': {
-      if (args.length < 2) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'unbonding-delegation requires delegator-address and validator-address arguments'
-        );
-      }
+      requireArgs(args, 2, ['delegator-address', 'validator-address'], 'staking unbonding-delegation');
       const [delegatorAddr, validatorAddr] = args;
       const result = await staking.unbondingDelegation({
         delegatorAddr,
@@ -59,14 +65,10 @@ export async function routeStakingQuery(
     }
 
     case 'unbonding-delegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'unbonding-delegations requires delegator-address argument'
-        );
-      }
-      const [delegatorAddr] = args;
-      const result = await staking.delegatorUnbondingDelegations({ delegatorAddr, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking unbonding-delegations');
+      requireArgs(remainingArgs, 1, ['delegator-address'], 'staking unbonding-delegations');
+      const [delegatorAddr] = remainingArgs;
+      const result = await staking.delegatorUnbondingDelegations({ delegatorAddr, pagination });
       return {
         unbondingResponses: result.unbondingResponses,
         pagination: result.pagination,
@@ -74,20 +76,17 @@ export async function routeStakingQuery(
     }
 
     case 'redelegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'redelegations requires delegator-address argument'
-        );
-      }
-      const [delegatorAddr] = args;
-      const srcValidatorAddr = args[1] || '';
-      const dstValidatorAddr = args[2] || '';
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking redelegations');
+      requireArgs(remainingArgs, 1, ['delegator-address'], 'staking redelegations');
+      const [delegatorAddr] = remainingArgs;
+      // Optional: src and dst validator addresses for filtering
+      const srcValidatorAddr = remainingArgs[1] || '';
+      const dstValidatorAddr = remainingArgs[2] || '';
       const result = await staking.redelegations({
         delegatorAddr,
         srcValidatorAddr,
         dstValidatorAddr,
-        pagination: defaultPagination,
+        pagination,
       });
       return {
         redelegationResponses: result.redelegationResponses,
@@ -96,32 +95,25 @@ export async function routeStakingQuery(
     }
 
     case 'validator': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'validator requires validator-address argument'
-        );
-      }
+      requireArgs(args, 1, ['validator-address'], 'staking validator');
       const [validatorAddr] = args;
       const result = await staking.validator({ validatorAddr });
       return { validator: result.validator };
     }
 
     case 'validators': {
-      const status = args[0] || '';
-      const result = await staking.validators({ status, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking validators');
+      // Optional: status filter
+      const status = remainingArgs[0] || '';
+      const result = await staking.validators({ status, pagination });
       return { validators: result.validators, pagination: result.pagination };
     }
 
     case 'validator-delegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'validator-delegations requires validator-address argument'
-        );
-      }
-      const [validatorAddr] = args;
-      const result = await staking.validatorDelegations({ validatorAddr, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking validator-delegations');
+      requireArgs(remainingArgs, 1, ['validator-address'], 'staking validator-delegations');
+      const [validatorAddr] = remainingArgs;
+      const result = await staking.validatorDelegations({ validatorAddr, pagination });
       return {
         delegationResponses: result.delegationResponses,
         pagination: result.pagination,
@@ -129,14 +121,10 @@ export async function routeStakingQuery(
     }
 
     case 'validator-unbonding-delegations': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'validator-unbonding-delegations requires validator-address argument'
-        );
-      }
-      const [validatorAddr] = args;
-      const result = await staking.validatorUnbondingDelegations({ validatorAddr, pagination: defaultPagination });
+      const { pagination, remainingArgs } = extractPaginationArgs(args, 'staking validator-unbonding-delegations');
+      requireArgs(remainingArgs, 1, ['validator-address'], 'staking validator-unbonding-delegations');
+      const [validatorAddr] = remainingArgs;
+      const result = await staking.validatorUnbondingDelegations({ validatorAddr, pagination });
       return {
         unbondingResponses: result.unbondingResponses,
         pagination: result.pagination,
@@ -154,37 +142,13 @@ export async function routeStakingQuery(
     }
 
     case 'historical-info': {
-      if (args.length < 1) {
-        throw new ManifestMCPError(
-          ManifestMCPErrorCode.QUERY_FAILED,
-          'historical-info requires height argument'
-        );
-      }
+      requireArgs(args, 1, ['height'], 'staking historical-info');
       const height = parseBigInt(args[0], 'height');
       const result = await staking.historicalInfo({ height });
       return { hist: result.hist };
     }
 
     default:
-      throw new ManifestMCPError(
-        ManifestMCPErrorCode.UNSUPPORTED_QUERY,
-        `Unsupported staking query subcommand: ${subcommand}`,
-        {
-          availableSubcommands: [
-            'delegation',
-            'delegations',
-            'unbonding-delegation',
-            'unbonding-delegations',
-            'redelegations',
-            'validator',
-            'validators',
-            'validator-delegations',
-            'validator-unbonding-delegations',
-            'pool',
-            'params',
-            'historical-info',
-          ],
-        }
-      );
+      throwUnsupportedSubcommand('query', 'staking', subcommand);
   }
 }

package/src/queries/utils.test.ts

@@ -1,5 +1,12 @@
 import { describe, it, expect } from 'vitest';
-import { parseBigInt, parseInt } from './utils.js';
+import {
+  parseBigInt,
+  parseInteger,
+  createPagination,
+  extractPaginationArgs,
+  DEFAULT_PAGE_LIMIT,
+  MAX_PAGE_LIMIT,
+} from './utils.js';
 import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
 
 describe('parseBigInt', () => {
@@ -38,24 +45,112 @@ describe('parseBigInt', () => {
   });
 });
 
-describe('parseInt', () => {
+describe('parseInteger', () => {
   it('should parse valid integer strings', () => {
-    expect(parseInt('0', 'status')).toBe(0);
-    expect(parseInt('123', 'status')).toBe(123);
-    expect(parseInt('-5', 'status')).toBe(-5);
+    expect(parseInteger('0', 'status')).toBe(0);
+    expect(parseInteger('123', 'status')).toBe(123);
+    expect(parseInteger('-5', 'status')).toBe(-5);
   });
 
   it('should throw ManifestMCPError for invalid integers', () => {
-    expect(() => parseInt('', 'status')).toThrow(ManifestMCPError);
-    expect(() => parseInt('abc', 'status')).toThrow(ManifestMCPError);
+    expect(() => parseInteger('', 'status')).toThrow(ManifestMCPError);
+    expect(() => parseInteger('abc', 'status')).toThrow(ManifestMCPError);
   });
 
   it('should have correct error code', () => {
     try {
-      parseInt('invalid', 'status');
+      parseInteger('invalid', 'status');
     } catch (error) {
       expect(error).toBeInstanceOf(ManifestMCPError);
       expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.QUERY_FAILED);
     }
   });
 });
+
+describe('createPagination', () => {
+  it('should use default limit when none provided', () => {
+    const pagination = createPagination();
+    expect(pagination.limit).toBe(DEFAULT_PAGE_LIMIT);
+    expect(pagination.offset).toBe(BigInt(0));
+    expect(pagination.countTotal).toBe(false);
+    expect(pagination.reverse).toBe(false);
+    expect(pagination.key).toEqual(new Uint8Array());
+  });
+
+  it('should use provided limit', () => {
+    const pagination = createPagination(BigInt(50));
+    expect(pagination.limit).toBe(BigInt(50));
+  });
+
+  it('should clamp limit to minimum of 1', () => {
+    const pagination = createPagination(BigInt(0));
+    expect(pagination.limit).toBe(BigInt(1));
+
+    const paginationNegative = createPagination(BigInt(-10));
+    expect(paginationNegative.limit).toBe(BigInt(1));
+  });
+
+  it('should clamp limit to maximum', () => {
+    const pagination = createPagination(BigInt(9999));
+    expect(pagination.limit).toBe(MAX_PAGE_LIMIT);
+  });
+});
+
+describe('extractPaginationArgs', () => {
+  it('should return default pagination when no --limit flag', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs(['arg1', 'arg2'], 'test');
+    expect(pagination.limit).toBe(DEFAULT_PAGE_LIMIT);
+    expect(remainingArgs).toEqual(['arg1', 'arg2']);
+  });
+
+  it('should extract --limit flag and value', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs(
+      ['arg1', '--limit', '50', 'arg2'],
+      'test'
+    );
+    expect(pagination.limit).toBe(BigInt(50));
+    expect(remainingArgs).toEqual(['arg1', 'arg2']);
+  });
+
+  it('should handle --limit at end of args', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs(
+      ['arg1', '--limit', '25'],
+      'test'
+    );
+    expect(pagination.limit).toBe(BigInt(25));
+    expect(remainingArgs).toEqual(['arg1']);
+  });
+
+  it('should handle --limit at start of args', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs(
+      ['--limit', '75', 'arg1'],
+      'test'
+    );
+    expect(pagination.limit).toBe(BigInt(75));
+    expect(remainingArgs).toEqual(['arg1']);
+  });
+
+  it('should throw for invalid limit value', () => {
+    expect(() =>
+      extractPaginationArgs(['--limit', 'abc'], 'test')
+    ).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for limit below minimum', () => {
+    expect(() =>
+      extractPaginationArgs(['--limit', '0'], 'test')
+    ).toThrow(ManifestMCPError);
+  });
+
+  it('should throw for limit above maximum', () => {
+    expect(() =>
+      extractPaginationArgs(['--limit', '9999'], 'test')
+    ).toThrow(ManifestMCPError);
+  });
+
+  it('should handle empty args array', () => {
+    const { pagination, remainingArgs } = extractPaginationArgs([], 'test');
+    expect(pagination.limit).toBe(DEFAULT_PAGE_LIMIT);
+    expect(remainingArgs).toEqual([]);
+  });
+});

package/src/queries/utils.ts

@@ -1,20 +1,86 @@
 import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
-import { parseBigIntWithCode } from '../transactions/utils.js';
+import { parseBigIntWithCode, requireArgs as requireArgsBase, extractFlag, filterConsumedArgs } from '../transactions/utils.js';
 
 /** Default page size limit for paginated queries to prevent resource exhaustion */
 export const DEFAULT_PAGE_LIMIT = BigInt(100);
 
+/** Maximum page size limit to prevent DoS */
+export const MAX_PAGE_LIMIT = BigInt(1000);
+
+/**
+ * Cosmos SDK pagination configuration
+ */
+export interface PaginationConfig {
+  readonly key: Uint8Array;
+  readonly offset: bigint;
+  readonly limit: bigint;
+  readonly countTotal: boolean;
+  readonly reverse: boolean;
+}
+
+/**
+ * Create pagination configuration with optional custom limit.
+ * Validates that limit is within acceptable bounds.
+ *
+ * @param limit - Optional custom limit (defaults to DEFAULT_PAGE_LIMIT)
+ * @returns Cosmos SDK pagination object
+ */
+export function createPagination(limit?: bigint): PaginationConfig {
+  let effectiveLimit = limit ?? DEFAULT_PAGE_LIMIT;
+
+  // Clamp to valid range
+  if (effectiveLimit < BigInt(1)) {
+    effectiveLimit = BigInt(1);
+  } else if (effectiveLimit > MAX_PAGE_LIMIT) {
+    effectiveLimit = MAX_PAGE_LIMIT;
+  }
+
+  return {
+    key: new Uint8Array(),
+    offset: BigInt(0),
+    limit: effectiveLimit,
+    countTotal: false,
+    reverse: false,
+  };
+}
+
 /**
- * Default pagination configuration for queries
- * Uses Cosmos SDK pagination format
+ * Default pagination configuration for queries (for backwards compatibility)
+ * @deprecated Use createPagination() instead for configurable limits
  */
-export const defaultPagination = {
-  key: new Uint8Array(),
-  offset: BigInt(0),
-  limit: DEFAULT_PAGE_LIMIT,
-  countTotal: false,
-  reverse: false,
-};
+export const defaultPagination = createPagination();
+
+/**
+ * Extract --limit flag from args and return pagination config with remaining args.
+ * Use this helper for paginated queries.
+ *
+ * @param args - The arguments array
+ * @param context - Context for error messages
+ * @returns Object with pagination config and filtered args
+ */
+export function extractPaginationArgs(
+  args: string[],
+  context: string
+): { pagination: PaginationConfig; remainingArgs: string[] } {
+  const { value: limitStr, consumedIndices } = extractFlag(args, '--limit', context);
+  const remainingArgs = filterConsumedArgs(args, consumedIndices);
+
+  let pagination: PaginationConfig;
+  if (limitStr) {
+    const limit = parseBigInt(limitStr, 'limit');
+    if (limit < BigInt(1) || limit > MAX_PAGE_LIMIT) {
+      throw new ManifestMCPError(
+        ManifestMCPErrorCode.QUERY_FAILED,
+        `Invalid limit: ${limit}. Must be between 1 and ${MAX_PAGE_LIMIT}.`
+      );
+    }
+    pagination = createPagination(limit);
+  } else {
+    pagination = createPagination();
+  }
+
+  return { pagination, remainingArgs };
+}
 
 /**
  * Safely parse a string to BigInt with proper error handling (for queries)
@@ -24,9 +90,10 @@ export function parseBigInt(value: string, fieldName: string): bigint {
 }
 
 /**
- * Safely parse a string to integer with proper error handling
+ * Safely parse a string to integer with proper error handling.
+ * Named parseInteger to avoid shadowing global parseInt.
  */
-export function parseInt(value: string, fieldName: string): number {
+export function parseInteger(value: string, fieldName: string): number {
   const parsed = Number.parseInt(value, 10);
   if (Number.isNaN(parsed)) {
     throw new ManifestMCPError(
@@ -36,3 +103,16 @@ export function parseInt(value: string, fieldName: string): number {
   }
   return parsed;
 }
+
+/**
+ * Validate that required arguments are present (for queries).
+ * Uses QUERY_FAILED error code by default.
+ */
+export function requireArgs(
+  args: string[],
+  minCount: number,
+  expectedNames: string[],
+  context: string
+): void {
+  requireArgsBase(args, minCount, expectedNames, context, ManifestMCPErrorCode.QUERY_FAILED);
+}