Poll session

Instructions

Implementation Reference

• src/server.js:342-375 (registration)

  Registration of the 'poll_interactsh_session' MCP tool, defining metadata, Zod inputSchema, and inline handler function that delegates to service.pollSession and applies filters.

  server.registerTool(
    'poll_interactsh_session',
    {
      title: 'Poll session',
      description:
        'Retrieves and decrypts interactions for a session. Optional filters let you match HTTP method, path, query, protocol, or free text.',
      inputSchema: {
        correlation_id: z.string(),
        method: z.string().optional(),
        path_contains: z.string().optional(),
        query_contains: z.string().optional(),
        protocol: z.string().optional(),
        text_contains: z.string().optional(),
      },
    },
    async ({ correlation_id, ...filters }) => {
      const payload = await service.pollSession(correlation_id);
      const sanitizedFilters = Object.fromEntries(
        Object.entries(filters)
          .filter(([, value]) => value !== undefined && value !== '')
          .map(([key, value]) => [key, typeof value === 'string' ? value : JSON.stringify(value)]),
      );
      const filteredEvents = applyEventFilters(payload.events, sanitizedFilters);
  
      return result({
        applied_filters: sanitizedFilters,
        total_events: payload.events.length,
        matched_events: filteredEvents.length,
        events: filteredEvents,
        extra: payload.extra,
        tld_data: payload.tld_data,
      });
    },
  );

• src/server.js:348-355 (schema)

  Zod input schema for the tool: requires correlation_id, optional filter fields (method, path_contains, query_contains, protocol, text_contains).

  inputSchema: {
    correlation_id: z.string(),
    method: z.string().optional(),
    path_contains: z.string().optional(),
    query_contains: z.string().optional(),
    protocol: z.string().optional(),
    text_contains: z.string().optional(),
  },

• src/server.js:357-374 (handler)

  Inline MCP tool handler: calls service.pollSession, sanitizes and applies filters to events, returns structured content with counts and filtered results.

  async ({ correlation_id, ...filters }) => {
    const payload = await service.pollSession(correlation_id);
    const sanitizedFilters = Object.fromEntries(
      Object.entries(filters)
        .filter(([, value]) => value !== undefined && value !== '')
        .map(([key, value]) => [key, typeof value === 'string' ? value : JSON.stringify(value)]),
    );
    const filteredEvents = applyEventFilters(payload.events, sanitizedFilters);
  
    return result({
      applied_filters: sanitizedFilters,
      total_events: payload.events.length,
      matched_events: filteredEvents.length,
      events: filteredEvents,
      extra: payload.extra,
      tld_data: payload.tld_data,
    });
  },

• src/server.js:73-88 (handler)

  Core InteractshService.pollSession method: authenticates and GET /poll endpoint, decrypts events using session's private key, normalizes extra/tld_data.

  async pollSession(correlationId) {
    const session = this.#requireSession(correlationId);
    const url = new URL('/poll', this.baseUrl);
    url.searchParams.set('id', session.correlationId);
    url.searchParams.set('secret', session.secretKey);
  
    const response = await this.#request(url, { method: 'GET' });
    const payload = await response.json();
  
    const events = this.#decryptEvents(session.privateKey, payload);
    return {
      events,
      extra: normaliseArray(payload.extra),
      tld_data: normaliseArray(payload.tlddata),
    };
  }

• src/server.js:197-242 (helper)

  Helper function to filter decrypted events by HTTP method, protocol, path/query contains, or free-text search across raw/parsed data.

  function applyEventFilters(events, filters) {
    if (!events.length) {
      return [];
    }
  
    const methodFilter = filters.method ? filters.method.toUpperCase() : undefined;
    const protocolFilter = filters.protocol ? filters.protocol.toLowerCase() : undefined;
    const pathFilter = filters.path_contains ? filters.path_contains.toLowerCase() : undefined;
    const queryFilter = filters.query_contains ? filters.query_contains.toLowerCase() : undefined;
    const textFilter = filters.text_contains ? filters.text_contains.toLowerCase() : undefined;
  
    return events
      .map((raw) => {
        const parsed = parseEvent(raw);
        return { raw, ...parsed };
      })
      .filter(({ raw, parsed, http, protocol }) => {
        if (methodFilter && (!http || http.method !== methodFilter)) {
          return false;
        }
        if (pathFilter && (!http || !http.pathLower.includes(pathFilter))) {
          return false;
        }
        if (queryFilter && (!http || !http.queryLower.includes(queryFilter))) {
          return false;
        }
        if (protocolFilter && (!protocol || protocol.toLowerCase() !== protocolFilter)) {
          return false;
        }
        if (textFilter) {
          const haystack = [raw, parsed ? JSON.stringify(parsed) : '', http?.fullPath ?? '']
            .join(' ')
            .toLowerCase();
          if (!haystack.includes(textFilter)) {
            return false;
          }
        }
        return true;
      })
      .map(({ raw, parsed, http, protocol }) => ({
        raw,
        protocol: protocol ?? undefined,
        http: http ?? undefined,
        parsed: parsed ?? undefined,
      }));
  }