Orchestrator/bahn/awesome-bahn-mcp-servers/AGENTS.md

# Awesome Bahn MCP Servers aktualisieren

> **⚠️ README.md NIEMALS direkt bearbeiten!**
> Die README.md wird ausschließlich durch `python3 generate-readme.py` aus `index.json` erzeugt. Direkte Änderungen an der README.md — egal ob manuell, durch LLMs oder Agenten — sind verboten. Änderungen gehören in `index.json`, `header.md` oder `footer.md`.

## Liste ergänzen

> Durchsuche das interne GitLab nach allen MCP Servern, prüfe Stars, letzte Aktivität und Sichtbarkeit. Aktualisiere `index.json` und generiere die README.md. Nur non-private Repos aufnehmen. Sortiere nach Stars absteigend.

## Liste aktualisieren

> Durchsuche das interne Gitlab nach allen Servern in der `index.json`, aktualisiere die Anzahl der Sterne und `last_activity`

Wenn ein Server verschwindet weise darauf hin und entferne ihn. Versuche ihn an anderer Stelle zu finden, da er vielleicht nur umgezogen wurde.

## Neuen MCP Server hinzufügen

> Füge den MCP Server <URL> zur awesome-bahn-mcp-servers Liste hinzu. Prüfe Stars, letzte Aktivität und ob das Repo non-private ist.

## Workflow

Bei jeder Änderung an der Liste — egal ob Auffrischen, Hinzufügen oder Entfernen:

1. **Immer zuerst `index.json` aktualisieren** — das ist die Single Source of Truth
2. **Jeden neuen oder geänderten Server dem User vorstellen** und nach Hinweisen fragen:
   - Ist der Server Bahn-spezifisch? Falls nein → `"note": "Nicht Bahn-spezifisch"`
   - Nur lokal nutzbar? → `"note": "Nur lokale Nutzung"`
   - Nur für proprietäres Wissen? → `"note": "Nur lokales proprietäres Wissen"`
   - Richtige Kategorie? User entscheidet
   - Sonstige Hinweise? User kann freien Text als `note` vergeben
3. **`python3 generate-readme.py` ausführen** — README.md niemals manuell editieren
4. Neuen Branch erstellen für Änderungen, Benutzer vorher fragen
5. **Immer vor jedem Commit `python3 generate-readme.py` ausführen** — sicherstellen, dass README.md aktuell ist
6. Eigenen Branch erstellen, Merge Request erstellen einen der CODEOWNERS assignen

## Regeln

- Nur Repos mit Sichtbarkeit `internal` oder `public` aufnehmen (nicht `private`)
- Stars und letzte Aktivität via GitLab API abfragen
- Forks standardmäßig ausschließen — via `glab api "projects/<path>"` und `forked_from_project` prüfen
- Forks nur aufnehmen wenn sie eigenen Mehrwert haben (nicht nur zum Listen)
- Playgrounds, leere Repos und Nicht-MCP-Server ausschließen
- Repos die noch in Entwicklung sind (leere Hülle) → `excluded[]` mit Grund
- Alle Texte auf Deutsch, englische Fachbegriffe beibehalten
- Proper Umlauts verwenden (ü, ö, ä, ß)
- Repo-Pfad: `$HOME/work/mcp/awesome-bahn-mcp`
- Remote: `git@ssh.git.tech.rz.db.de:beta/ai/awesome-bahn-mcp-servers.git`

## index.json

Die Datei `index.json` ist die Single Source of Truth. Die README.md wird daraus generiert — niemals manuell editieren.

Struktur:

- `servers[]` — Alle Server mit folgenden Feldern:
  - `url` — GitLab URL
  - `name` — Anzeigename
  - `description` — Kurzbeschreibung
  - `stars` — Anzahl der Sterne
  - `contributors` — Anzahl der Contributors (optional)
  - `commits` — Anzahl der Commits (optional)
  - `last_activity` — Datum der letzten Aktivität (YYYY-MM-DD)
  - `status` — "legit" für aufgenommene Server
  - `category` — Eine der definierten Kategorien
  - `note` — Optionaler Hinweis (z.B. "Nicht Bahn-spezifisch")
  - `beta` — `true` für BETA-Team Server (erscheinen mit Badge)
  - `official` — `true` für offizielle DB-Server (erscheinen mit OFFICIAL Badge)
- `false_positives[]` — Repos die kein MCP Server sind und beim nächsten Scan ignoriert werden
- `excluded[]` — Repos die bewusst ausgeschlossen wurden (mit Grund)

Beim Auffrischen der Liste:
1. `index.json` lesen
2. GitLab API durchsuchen: `glab api "projects?search=mcp&per_page=100&page=N"`
3. Zusätzlich Blob-Suche nach MCP-SDK-Nutzung: `glab api "search?scope=blobs&search=modelcontextprotocol&per_page=100"` — findet Repos die das MCP SDK nutzen, aber nicht "mcp" im Namen haben
4. Zusätzlich Blob-Suche nach MCP-Dependencies: `glab api "search?scope=blobs&search=mcp>=&per_page=100"` (Python) und `glab api "search?scope=blobs&search=@modelcontextprotocol/sdk&per_page=100"` (TypeScript) — findet Repos die das MCP SDK als Dependency nutzen
5. Neue Repos gegen `false_positives` und `excluded` prüfen — diese nicht aufnehmen
6. Neue Repos auf Forks prüfen: `glab api "projects/<path>"` → `forked_from_project`
7. Bestehende Server-Daten (stars, last_activity) aktualisieren
8. Neue Server einzeln dem User vorstellen: `open <url>` ausführen um das Repo im Browser zu öffnen, dann nach Urteil fragen (Kategorie, Notes, aufnehmen oder nicht)
9. `python3 generate-readme.py` ausführen um README.md zu generieren

## Kategorien

- AI und GenAI
- DB-Kontext und Wissen
- Daten und Analytik
- DevOps und Infrastruktur
- Enterprise Architecture und Governance
- Fachspezifisch
- Kommunikation und Zusammenarbeit
- Monitoring
- Produktivität und Automatisierung
- Reisenden-Information (RIS)
- Suche und Code-Analyse

## README generieren

```
python3 generate-readme.py
```

Das Script liest `index.json` und erzeugt `README.md`. Keine externen Abhängigkeiten — nur Python stdlib. BETA-Server (`"beta": true`) und OFFICIAL-Server (`"official": true`) stehen immer oben innerhalb ihrer Kategorie. Community-Server werden nach Kategorie gruppiert und nach Stars absteigend sortiert. Ausgabeformat ist Bullet-Listen (keine Tabellen).

## Troubleshooting

### glab API gibt keine Daten zurück

Prüfe ob `GITLAB_TOKEN` Umgebungsvariable gesetzt ist — diese überschreibt das glab-Token:

```bash
echo $GITLAB_TOKEN
unset GITLAB_TOKEN
glab auth status
```

Falls das Token abgelaufen ist:
```bash
glab auth login --hostname ssh.git.tech.rz.db.de
```

### Server nicht mehr erreichbar (404)

Server aus `servers[]` entfernen und zu `false_positives[]` hinzufügen mit Grund "Repo gelöscht (404 Not Found)".

### Berechtigungsfehler bei glab config

```bash
chmod 600 ~/.config/glab-cli/config.yml
```