qring-mcp

Instructions

Implementation Reference

• src/mcp/server.ts:501-528 (registration)

  The 'audit_log' tool is defined and registered here within the MCP server setup.

  server.tool(
    "audit_log",
    "Query the audit log for secret access history (observer effect). Shows who accessed what and when.",
    {
      key: z.string().optional().describe("Filter by key"),
      action: z
        .enum(["read", "write", "delete", "list", "export", "generate", "entangle", "tunnel", "teleport", "collapse"])
        .optional()
        .describe("Filter by action"),
      limit: z.number().optional().default(20).describe("Max events to return"),
    },
    async (params) => {
      const events = queryAudit({
        key: params.key,
        action: params.action,
        limit: params.limit,
      });
  
      if (events.length === 0) return text("No audit events found");
  
      const lines = events.map((e) => {
        const parts = [e.timestamp, e.action];
        if (e.key) parts.push(e.key);
        if (e.scope) parts.push(`[${e.scope}]`);
        if (e.env) parts.push(`env:${e.env}`);
        if (e.detail) parts.push(e.detail);
        return parts.join(" | ");
      });

• src/mcp/server.ts:512-528 (handler)

  The handler for 'audit_log' which invokes the queryAudit core function.

  async (params) => {
    const events = queryAudit({
      key: params.key,
      action: params.action,
      limit: params.limit,
    });
  
    if (events.length === 0) return text("No audit events found");
  
    const lines = events.map((e) => {
      const parts = [e.timestamp, e.action];
      if (e.key) parts.push(e.key);
      if (e.scope) parts.push(`[${e.scope}]`);
      if (e.env) parts.push(`env:${e.env}`);
      if (e.detail) parts.push(e.detail);
      return parts.join(" | ");
    });

• src/core/observer.ts:71-110 (handler)

  The actual logic implementation for querying the audit log by reading from the audit file.

  export function queryAudit(query: AuditQuery = {}): AuditEvent[] {
    const path = getAuditPath();
    if (!existsSync(path)) return [];
  
    try {
      const lines = readFileSync(path, "utf8")
        .split("\n")
        .filter((l) => l.trim());
  
      let events: AuditEvent[] = lines
        .map((line) => {
          try {
            return JSON.parse(line) as AuditEvent;
          } catch {
            return null;
          }
        })
        .filter((e): e is AuditEvent => e !== null);
  
      if (query.key) {
        events = events.filter((e) => e.key === query.key);
      }
      if (query.action) {
        events = events.filter((e) => e.action === query.action);
      }
      if (query.since) {
        const since = new Date(query.since).getTime();
        events = events.filter(
          (e) => new Date(e.timestamp).getTime() >= since,
        );
      }
  
      events.sort(
        (a, b) =>
          new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime(),
      );
  
      if (query.limit) {
        events = events.slice(0, query.limit);
      }

• src/core/observer.ts:64-69 (schema)

  The AuditQuery type definition used for input validation of the audit query.

  export interface AuditQuery {
    key?: string;
    action?: AuditAction;
    since?: string;
    limit?: number;
  }