qring-mcp

Instructions

Implementation Reference

• src/core/agent.ts:52-125 (handler)

  The core logic for the agent_scan tool is implemented in runHealthScan in src/core/agent.ts. It scans global and project secrets for decay, anomalies, and performs auto-rotation if enabled.

  export function runHealthScan(config: Partial<AgentConfig> = {}): AgentReport {
    const cfg = { ...defaultConfig(), ...config };
  
    const report: AgentReport = {
      timestamp: new Date().toISOString(),
      totalSecrets: 0,
      healthy: 0,
      stale: 0,
      expired: 0,
      anomalies: 0,
      rotated: [],
      warnings: [],
    };
  
    // Scan global scope
    const globalEntries = listSecrets({ scope: "global", source: "agent" });
  
    // Scan project scopes
    const projectEntries = cfg.projectPaths.flatMap((pp) =>
      listSecrets({ scope: "project", projectPath: pp, source: "agent" }),
    );
  
    const allEntries = [...globalEntries, ...projectEntries];
    report.totalSecrets = allEntries.length;
  
    for (const entry of allEntries) {
      if (!entry.envelope) continue;
  
      const decay = checkDecay(entry.envelope);
  
      if (decay.isExpired) {
        report.expired++;
        report.warnings.push(
          `EXPIRED: ${entry.key} [${entry.scope}] — expired ${decay.timeRemaining}`,
        );
  
        if (cfg.autoRotate) {
          const fmt = (entry.envelope?.meta.rotationFormat ?? "api-key") as import("./noise.js").NoiseFormat;
          const prefix = entry.envelope?.meta.rotationPrefix;
          const newValue = generateSecret({ format: fmt, prefix });
          setSecret(entry.key, newValue, {
            scope: entry.scope,
            projectPath: cfg.projectPaths[0],
            source: "agent",
          });
          report.rotated.push(entry.key);
          logAudit({
            action: "write",
            key: entry.key,
            scope: entry.scope,
            source: "agent",
            detail: "auto-rotated by agent (expired)",
          });
          fireHooks({
            action: "rotate",
            key: entry.key,
            scope: entry.scope,
            timestamp: new Date().toISOString(),
            source: "agent",
          }, entry.envelope?.meta.tags).catch(() => {});
        }
      } else if (decay.isStale) {
        report.stale++;
        report.warnings.push(
          `STALE: ${entry.key} [${entry.scope}] — ${decay.lifetimePercent}% lifetime, ${decay.timeRemaining} remaining`,
        );
      } else {
        report.healthy++;
      }
    }
  
    // Check for anomalies
    const anomalies = detectAnomalies();
    report.anomalies = anomalies.length;

• src/mcp/server.ts:1007-1028 (registration)

  The 'agent_scan' tool is registered in src/mcp/server.ts, using the runHealthScan function from src/core/agent.ts as its handler.

  server.tool(
    "agent_scan",
    "Run an autonomous agent health scan: checks decay, staleness, anomalies, and optionally auto-rotates expired secrets. Returns a structured report.",
    {
      autoRotate: z
        .boolean()
        .optional()
        .default(false)
        .describe("Auto-rotate expired secrets with generated values"),
      projectPaths: z
        .array(z.string())
        .optional()
        .describe("Project paths to monitor"),
    },
    async (params) => {
      const report = runHealthScan({
        autoRotate: params.autoRotate,
        projectPaths: params.projectPaths ?? [process.cwd()],
      });
      return text(JSON.stringify(report, null, 2));
    },
  );