feat(config): add six-client MCP configuration doctor and safe repair tool #977

New Issue

2026-07-29T22:27:51-05:00

jcwalker3 commented

2026-07-29 22:27:51 -05:00

Summary

Add a six-client MCP configuration doctor and safe repair tool that discovers, audits, and (with explicit operator confirmation) safely repairs Gitea MCP configuration across all supported execution clients.

This is a secondary operational-hardening improvement. It must not block, close, expand, replace, or delay the current multi-LLM mission (#963) or interrupt PR #976.

Scope: six independent execution clients

Gitea MCP configuration is managed independently across six execution clients:

Claude Code
Codex
Gemini CLI
Grok
Kimi K
Antigravity (AGY)

Gemini CLI and Antigravity may both use Gemini-family models, but they are separate execution clients with separate configuration locations and must be discovered, audited, and repaired independently.

Do not assume that all six clients use the same configuration format, file location, namespace structure, or client-identity value.

Known client-identity values

Client	Known `GITEA_MCP_CLIENT` value
Claude Code	`claude_code`
Codex	`codex`
Gemini CLI	`gemini`
Grok	`grok`

Do not guess the expected GITEA_MCP_CLIENT values, paths, or formats for Kimi K or Antigravity. The tool must derive them from authoritative templates, documented client definitions, existing valid configurations, or verified runtime evidence. If the expected value cannot be established safely, report it as unresolved and do not repair it.

Problem statement

Temporary MCP environment changes—such as removing and later restoring GITEA_MCP_CLIENT—currently require client-specific manual commands. Because every client may use different files and formats, configurations can become incomplete, inconsistent, malformed, stale, or bound to the wrong profiles and repositories.

Required capabilities

Discovery and audit

Discover which of the six supported clients are installed.
Locate every authoritative MCP configuration file for each client.
Distinguish active configuration from backups, caches, logs, examples, generated files, and stale copies.
Support explicitly defined JSON, JSONC, TOML, YAML, and other validated client formats.
Treat Gemini CLI and Antigravity as separate configuration targets.
Verify every configured Gitea MCP namespace, including expected role namespaces such as:
- author
- reviewer
- merger
- controller
- reconciler

Detection surface

Detect:

missing required environment keys;
incorrect client identities;
wrong profiles or roles;
missing namespaces;
unexpected namespaces;
duplicate namespace definitions;
inconsistent repository bindings;
stale or conflicting configuration copies;
unsupported GITEA_* overrides;
malformed configuration;
configuration drift between namespaces;
configuration drift between clients;
values that will not take effect until restart;
configurations that reference missing executables or repository paths.

Identity isolation

Verify that client and session identity settings remain isolated between the six clients.
Never require all clients to share the same identity value.

Reporting

Provide a read-only audit mode.
Produce both human-readable and machine-readable reports.
Clearly distinguish findings as:
- correct;
- missing;
- incorrect;
- unresolved;
- unsafe to repair;
- repaired but restart required.

Safe repair

Provide a dry-run repair plan showing the exact files, fields, old values, proposed values, and restart consequences.
Allow the operator to select exactly which clients, files, namespaces, and fields may be repaired.
Require explicit confirmation before writing.
Create timestamped backups before every repair.
Preserve unrelated configuration and formatting where practical.
Validate the complete resulting syntax before replacing a file.
Write replacements atomically.
Verify the repaired configuration afterward.
Provide safe rollback using the generated backup.
Be idempotent: correct configurations must produce no changes.
Clearly report which applications must be completely restarted.
Support future clients through explicit adapters without broadly accepting unknown formats or structures.

Security and fail-closed requirements

Never display, copy, rewrite, log, or expose credentials or tokens.
Redact secrets in human-readable and machine-readable output.
Do not transfer credentials between clients.
Do not search unrestricted user directories when authoritative configuration locations are known.
Do not edit caches, logs, temporary files, or backup files as active configuration.
Fail closed when the client, file, format, structure, expected identity, profile, repository, or repair target is uncertain.
A failure while repairing one client must not damage another client.
Partial failure must not leave malformed or partially written configuration.
A repair must not weaken profile, role, repository, provenance, parity, permission, or mutation gates.
The tool must never restart applications or MCP processes without a separate explicit operator action.

Acceptance criteria (automated tests required)

Correct configurations for all six clients pass unchanged.
Each client is discovered independently.
Gemini CLI and Antigravity are treated as separate configuration targets.
Missing client identity is detected.
An incorrect client identity is detected.
A safely known missing value can be repaired.
Unknown Kimi K or Antigravity identity values are not guessed.
JSON, JSONC, TOML, and YAML adapters handle supported configurations safely.
Multiple namespaces within one client are verified.
Missing and duplicate namespaces are detected.
Incorrect profiles and repository bindings are detected.
Unsupported GITEA_* variables remain rejected.
Active files are distinguished from backups, caches, logs, and stale copies.
Unrelated configuration remains byte-equivalent where practical.
Dry-run performs no writes.
Every repair creates a valid timestamped backup.
Rollback restores the prior valid configuration.
Repeated repair is idempotent.
Malformed or unknown configurations fail without modification.
Secrets are redacted from all output.
Partial failure cannot leave corrupted configuration.
One client’s repair cannot modify another client’s configuration.
Atomic replacement protects against interrupted writes.
Post-repair verification confirms the intended state.
Restart-required reporting identifies the correct affected clients.
The tool does not weaken any Gitea workflow enforcement gate.

Priority and relationship

Priority: secondary operational-hardening improvement (nice-to-have relative to the active multi-LLM mission).
Immediate priority remains completing PR #976 and continuing issue #963’s multi-client concurrency mission.
This configuration-doctor issue must not block, close, expand, replace, or delay #963.
Do not change #963’s accepted canary scope as part of this work.
The future configuration doctor must support all six clients regardless of the current #963 canary scope.
Do not treat this issue as a prerequisite for the current multi-LLM mission.

Out of scope (for this issue’s tracking)

Implementation is deferred until this issue is deliberately claimed after #976/#963 mission progress.
No lock, branch, worktree, or PR should be opened solely because this issue exists.

## Summary Add a **six-client MCP configuration doctor and safe repair tool** that discovers, audits, and (with explicit operator confirmation) safely repairs Gitea MCP configuration across all supported execution clients. This is a **secondary operational-hardening** improvement. It must **not** block, close, expand, replace, or delay the current multi-LLM mission (#963) or interrupt PR #976. ## Scope: six independent execution clients Gitea MCP configuration is managed independently across six execution clients: 1. **Claude Code** 2. **Codex** 3. **Gemini CLI** 4. **Grok** 5. **Kimi K** 6. **Antigravity (AGY)** **Gemini CLI** and **Antigravity** may both use Gemini-family models, but they are **separate execution clients** with separate configuration locations and must be discovered, audited, and repaired **independently**. Do **not** assume that all six clients use the same configuration format, file location, namespace structure, or client-identity value. ### Known client-identity values | Client | Known `GITEA_MCP_CLIENT` value | |--------|--------------------------------| | Claude Code | `claude_code` | | Codex | `codex` | | Gemini CLI | `gemini` | | Grok | `grok` | Do **not** guess the expected `GITEA_MCP_CLIENT` values, paths, or formats for **Kimi K** or **Antigravity**. The tool must derive them from authoritative templates, documented client definitions, existing valid configurations, or verified runtime evidence. If the expected value cannot be established safely, report it as **unresolved** and **do not repair** it. ## Problem statement Temporary MCP environment changes—such as removing and later restoring `GITEA_MCP_CLIENT`—currently require client-specific manual commands. Because every client may use different files and formats, configurations can become incomplete, inconsistent, malformed, stale, or bound to the wrong profiles and repositories. ## Required capabilities ### Discovery and audit * Discover which of the six supported clients are installed. * Locate every authoritative MCP configuration file for each client. * Distinguish active configuration from backups, caches, logs, examples, generated files, and stale copies. * Support explicitly defined JSON, JSONC, TOML, YAML, and other validated client formats. * Treat Gemini CLI and Antigravity as separate configuration targets. * Verify every configured Gitea MCP namespace, including expected role namespaces such as: * author * reviewer * merger * controller * reconciler ### Detection surface Detect: * missing required environment keys; * incorrect client identities; * wrong profiles or roles; * missing namespaces; * unexpected namespaces; * duplicate namespace definitions; * inconsistent repository bindings; * stale or conflicting configuration copies; * unsupported `GITEA_*` overrides; * malformed configuration; * configuration drift between namespaces; * configuration drift between clients; * values that will not take effect until restart; * configurations that reference missing executables or repository paths. ### Identity isolation * Verify that client and session identity settings remain isolated between the six clients. * Never require all clients to share the same identity value. ### Reporting * Provide a read-only audit mode. * Produce both human-readable and machine-readable reports. * Clearly distinguish findings as: * correct; * missing; * incorrect; * unresolved; * unsafe to repair; * repaired but restart required. ### Safe repair * Provide a dry-run repair plan showing the exact files, fields, old values, proposed values, and restart consequences. * Allow the operator to select exactly which clients, files, namespaces, and fields may be repaired. * Require explicit confirmation before writing. * Create timestamped backups before every repair. * Preserve unrelated configuration and formatting where practical. * Validate the complete resulting syntax before replacing a file. * Write replacements atomically. * Verify the repaired configuration afterward. * Provide safe rollback using the generated backup. * Be idempotent: correct configurations must produce no changes. * Clearly report which applications must be completely restarted. * Support future clients through explicit adapters without broadly accepting unknown formats or structures. ## Security and fail-closed requirements * Never display, copy, rewrite, log, or expose credentials or tokens. * Redact secrets in human-readable and machine-readable output. * Do not transfer credentials between clients. * Do not search unrestricted user directories when authoritative configuration locations are known. * Do not edit caches, logs, temporary files, or backup files as active configuration. * Fail closed when the client, file, format, structure, expected identity, profile, repository, or repair target is uncertain. * A failure while repairing one client must not damage another client. * Partial failure must not leave malformed or partially written configuration. * A repair must not weaken profile, role, repository, provenance, parity, permission, or mutation gates. * The tool must never restart applications or MCP processes without a separate explicit operator action. ## Acceptance criteria (automated tests required) 1. Correct configurations for all six clients pass unchanged. 2. Each client is discovered independently. 3. Gemini CLI and Antigravity are treated as separate configuration targets. 4. Missing client identity is detected. 5. An incorrect client identity is detected. 6. A safely known missing value can be repaired. 7. Unknown Kimi K or Antigravity identity values are not guessed. 8. JSON, JSONC, TOML, and YAML adapters handle supported configurations safely. 9. Multiple namespaces within one client are verified. 10. Missing and duplicate namespaces are detected. 11. Incorrect profiles and repository bindings are detected. 12. Unsupported `GITEA_*` variables remain rejected. 13. Active files are distinguished from backups, caches, logs, and stale copies. 14. Unrelated configuration remains byte-equivalent where practical. 15. Dry-run performs no writes. 16. Every repair creates a valid timestamped backup. 17. Rollback restores the prior valid configuration. 18. Repeated repair is idempotent. 19. Malformed or unknown configurations fail without modification. 20. Secrets are redacted from all output. 21. Partial failure cannot leave corrupted configuration. 22. One client’s repair cannot modify another client’s configuration. 23. Atomic replacement protects against interrupted writes. 24. Post-repair verification confirms the intended state. 25. Restart-required reporting identifies the correct affected clients. 26. The tool does not weaken any Gitea workflow enforcement gate. ## Priority and relationship * **Priority:** secondary operational-hardening improvement (`nice-to-have` relative to the active multi-LLM mission). * Immediate priority remains completing **PR #976** and continuing issue **#963**’s multi-client concurrency mission. * This configuration-doctor issue must **not** block, close, expand, replace, or delay **#963**. * Do **not** change #963’s accepted canary scope as part of this work. * The future configuration doctor must support **all six clients** regardless of the current #963 canary scope. * Do **not** treat this issue as a prerequisite for the current multi-LLM mission. ## Out of scope (for this issue’s tracking) * Implementation is deferred until this issue is deliberately claimed after #976/#963 mission progress. * No lock, branch, worktree, or PR should be opened solely because this issue exists.

jcwalker3 added the nice-to-have mcp security testing reliability type:feature status:ready workflow-hardening safety mcp-health labels 2026-07-29 22:27:52 -05:00

jcwalker3 referenced this issue

2026-07-30 01:57:00 -05:00

feat(controller): expose native instance-level fleet identity and health snapshots #978

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#977