agentic-community / agentic-community/mcp-gateway-registry
Add auto-generated Configuration Reference endpoint and UI tab
- 主要语言
- Python
- 星标
- 912
- 派生
- 234
- 平均合并
- 1 天 11 小时
- 30 天内合并 PR
- 62
描述
## Problem Statement
The registry has 80+ configuration parameters across 11 groups (auth, storage, embeddings, security scanning, etc.). Today, configuration documentation is maintained in a static `docs/configuration.md` file (700+ lines) that must be manually kept in sync with the Pydantic `Settings` class in `registry/core/config.py`. When new settings are added, the documentation inevitably falls behind.
The existing `/api/config/full` endpoint shows current **values** of config parameters but provides no documentation about what each parameter does, what values are valid, or what the environment variable name is.
## Proposed Solution
Add a `/api/config/docs` endpoint that auto-generates configuration parameter documentation directly from the Pydantic `Settings` model -- similar to how FastAPI auto-generates `/docs` from route definitions.
This requires:
1. Adding `Field(description=...)` to all settings fields in `config.py`
2. Creating a new `/api/config/docs` endpoint that returns grouped, documented config parameters with types, defaults, env var names, and descriptions
3. Adding a "Config Reference" tab in the existing ConfigPanel UI component
## User Stories
- As an operator, I want to see what configuration parameters are available and what they do without reading source code or a separate docs file
- As a developer, I want config documentation that is always in sync with the code so I never deploy with outdated docs
- As an admin viewing the Settings page, I want a "Config Reference" tab alongside the "Current Values" view that documents all available parameters
## Acceptance Criteria
- [ ] All Settings fields in `config.py` have `Field(description=...)` annotations
- [ ] `GET /api/config/docs` returns grouped config parameter documentation (no auth required for read-only schema info)
- [ ] Each parameter in the response includes: name, env_var, type, default, description, group, is_sensitive, constraints (min/max/options)
- [ ] Frontend ConfigPanel has a "Config Reference" tab showing the documentation
- [ ] Config Reference tab supports search/filter by env var name, description, and label
- [ ] Sensitive fields are documented but their defaults are not exposed
- [ ] The endpoint works without any external dependencies (no database needed)
- [ ] Existing `/api/config/full` and `/api/config/export` endpoints are unchanged
- [ ] A regression test verifies all Settings fields have non-empty descriptions
## Technical Approach
### Backend
- Add `Field(description=...)` to all 80+ Settings fields in `registry/core/config.py`
- Add `GET /api/config/docs` endpoint to `registry/api/config_routes.py` that introspects `Settings.model_fields` to extract type, description, default, and constraints
- Reuse existing `CONFIG_GROUPS` dict for grouping (consistent with `/api/config/full`)
- Cache the docs response at module level (schema is static at runtime, build once)
- No authentication required (returns schema metadata only, no runtime values)
- Handle both `typing.Union` and Python 3.10+ `types.UnionType` for type introspection
### Frontend
- New `ConfigReferencePanel.tsx` component that fetches from `/api/config/docs`
- Tab switcher in existing `ConfigPanel.tsx`: "Current Values" | "Config Reference"
- Reuse existing search and collapsible group patterns
- Show env var name, type badge, default value, description, and constraints for each parameter
- Hide export dropdown on "Config Reference" tab (read-only documentation)
### Response Shape
```json
{
"groups": [
{
"id": "auth",
"title": "Authentication",
"order": 3,
"fields": [
{
"name": "auth_provider",
"env_var": "AUTH_PROVIDER",
"label": "Auth Provider",
"type": "string",
"default": "cognito",
"description": "Authentication provider: cognito, keycloak, entra, or github",
"is_sensitive": false,
"is_required": false,
"constraints": {}
}
]
}
],
"total_fields": 76,
"total_groups": 11
}
```
## Out of Scope
- Config editing/updating via the UI (read-only reference only)
- Auto-generating `docs/configuration.md` from code (future enhancement)
- Config validation before applying (future enhancement)
- Comparing config between environments
## Design Documents
Full design documents (LLD and expert review) available in `.scratchpad/config-docs/`.
贡献指南
评估
这个 Issue 还没有评估数据。