qring-mcp

Instructions

Implementation Reference

• src/core/keyring.ts:300-346 (handler)

  The implementation of the listSecrets function which retrieves, parses, and validates secrets from the keyring.

  export function listSecrets(opts: KeyringOptions = {}): SecretEntry[] {
    const source = opts.source ?? "cli";
    const services: { service: string; scope: Scope }[] = [];
  
    if (!opts.scope || opts.scope === "global") {
      services.push({ service: globalService(), scope: "global" });
    }
  
    if ((!opts.scope || opts.scope === "project") && opts.projectPath) {
      services.push({
        service: projectService(opts.projectPath),
        scope: "project",
      });
    }
  
    const results: SecretEntry[] = [];
    const seen = new Set<string>();
  
    for (const { service, scope } of services) {
      try {
        const credentials = findCredentials(service);
        for (const cred of credentials) {
          const id = `${scope}:${cred.account}`;
          if (seen.has(id)) continue;
          seen.add(id);
  
          const envelope = parseEnvelope(cred.password) ?? wrapLegacy(cred.password);
          const decay = checkDecay(envelope);
  
          results.push({
            key: cred.account,
            scope,
            envelope,
            decay,
          });
        }
      } catch {
        // keyring unavailable
      }
    }
  
    if (!opts.silent) {
      logAudit({ action: "list", source });
    }
  
    return results.sort((a, b) => a.key.localeCompare(b.key));
  }

• src/mcp/server.ts:99-125 (registration)

  The registration of the "list_secrets" MCP tool and the handler logic that calls the core listSecrets implementation.

  server.tool(
    "list_secrets",
    "List all secret keys with quantum metadata (scope, decay status, superposition states, entanglement, access count). Values are never exposed. Supports filtering by tag, expiry state, and key pattern.",
    {
      scope: scopeSchema,
      projectPath: projectPathSchema,
      tag: z.string().optional().describe("Filter by tag"),
      expired: z.boolean().optional().describe("Show only expired secrets"),
      stale: z.boolean().optional().describe("Show only stale secrets (75%+ decay)"),
      filter: z.string().optional().describe("Glob pattern on key name (e.g., 'API_*')"),
    },
    async (params) => {
      let entries = listSecrets(opts(params));
  
      if (params.tag) {
        entries = entries.filter((e) =>
          e.envelope?.meta.tags?.includes(params.tag!),
        );
      }
      if (params.expired) {
        entries = entries.filter((e) => e.decay?.isExpired);
      }
      if (params.stale) {
        entries = entries.filter(
          (e) => e.decay?.isStale && !e.decay?.isExpired,
        );
      }