qring-mcp

Instructions

Implementation Reference

• src/core/agent.ts:51-121 (handler)

  The main logic for the agent_scan tool, which performs a health check on secrets, handles rotation, and detects anomalies.

  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 newValue = generateSecret({ format: "api-key" });
          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)",
          });
        }
      } 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;
    for (const a of anomalies) {
      report.warnings.push(`ANOMALY [${a.type}]: ${a.description}`);
    }
  
    return report;
  }

• src/mcp/server.ts:611-630 (registration)

  Registration of the 'agent_scan' tool with MCP server, including input schema definition and invocation of runHealthScan.

  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));

• src/mcp/server.ts:614-624 (schema)

  Input schema definition for the 'agent_scan' tool using Zod.

  {
    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"),
  },