freemapperEnglish

Handbuch › freemapper-courseplan

3. Mit einem KI-Assistenten

Der Assistent legt die Bahnen für dich. Dafür ist freemapper-courseplan ein „MCP-Server“, ein Werkzeug, das KI-Assistenten nutzen können. Das Programm hat selbst keine KI. Der Assistent ruft dieselben Bearbeitungsfunktionen auf wie die Kommandozeile, und jeder Aufruf speichert in deine Projektdatei.

Einmal einrichten

  • Claude Desktop:

    1. Einstellungen > Entwickler > Konfiguration bearbeiten öffnen.

    2. In die Datei claude_desktop_config.json eintragen, mit deinem eigenen Pfad (unter Windows mit doppelten Backslashes \\):

      {
  "mcpServers": {
    "freemapper-courseplan": {
      "command": "/Users/anna/Documents/freemapper-courseplan/freemapper-courseplan",
      "args": ["mcp"]
    }
  }
}

    3. Claude Desktop neu starten.

  • Claude Code: im Terminal claude mcp add freemapper-courseplan -- /Pfad/zu/freemapper-courseplan mcp eingeben.
  • Andere Assistenten: Jeder Assistent mit MCP-Unterstützung nimmt denselben Eintrag: das Programm und das Argument mcp.

Der Assistent liest die Werkzeugtexte in der Sprache deines Systems. Willst du die Sprache festlegen, schreibe "--lang", "de" vor "mcp" in die Argumente oder setze FREEMAPPER_LANG=de in der Umgebung des Programms. Werkzeugnamen und Feldnamen bleiben in jeder Sprache Englisch.

Vom Assistenten einrichten lassen

Das Archiv enthält neben dem Programm die READMEs, die Lizenz, dieses Handbuch und AGENTS.md, eine Anleitung für KI-Assistenten. Ein Assistent, der Befehle auf deinem Computer ausführen kann (etwa Claude Code oder Codex), lädt das Programm herunter, prüft und entpackt es nach den Schritten in dieser Datei und arbeitet dann über die Befehlszeile; einen Eintrag braucht er nicht. Nur ein Assistent, der keine Befehle ausführen kann, braucht den Eintrag von oben. Sag ihm:

Lies AGENTS.md von github.com/HenryJobst/freemapper-courseplan und richte freemapper-courseplan ein.

Auf einem Mac entfernt er die Sperre für nicht signierte Programme und sagt dir das. Je nach Einstellung fragt er vor jedem Befehl. Claude Desktop führt keine Befehle aus; dort trägst du das Programm von Hand ein, wie oben beschrieben.

Eine Bahn legen

Der Assistent sieht die Karte nicht. Er kann ihre Ausdehnung abfragen und für einen Punkt die Kartenobjekte im Umkreis, jeweils mit Symbolnummer, Art (Punkt, Linie, Fläche) und Abstand. Namen wie „Südtür“ oder „Sporthalle“ kennt er nicht, und wo ein Objekt genau liegt, sagt ihm die Abfrage auch nicht. Gib ihm deshalb Positionen vor, in Kartenmillimetern oder bezogen auf die Ausdehnung der Karte, zum Beispiel:

Lege eine Veranstaltung aus ~/karten/halle.omap an. Setze den Start ein Viertel vom linken Rand auf halbe Höhe und das Ziel 10 mm rechts daneben. Setze drei Posten über die Karte verteilt und sag mir zu jedem, welche Kartenobjekte im Umkreis von 2 mm liegen. Lege daraus die Bahn „Kurz“ für die Kategorie D10 an, setze die Postennummern und sag mir die Länge.

Der Assistent geht dann so vor:

  1. Er legt die Veranstaltung an. Die Projektdatei liegt neben der Karte und heißt halle.courseplan.toml.
  2. Er fragt die Ausdehnung der Karte ab, also ihre kleinste und größte Ecke in Kartenmillimetern, den Maßstab und die Kartenart, und rechnet daraus die Positionen aus.
  3. Er setzt Start, Ziel und Posten an diese Positionen.
  4. Er fragt für jeden Posten die Kartenobjekte in der Nähe ab und nennt dir Symbolnummern und Abstände, etwa „Symbol 521, Fläche, 0,4 mm“. Was das Symbol bedeutet, schlägst du im Symbolsatz der Karte nach.
  5. Er legt die Bahn an, setzt die Postennummern und liest Länge und Anstieg.

Du kannst in einem späteren Gespräch weitermachen. Gib dem Assistenten den Pfad der Projektdatei, dann setzt er dort an.

Was du wissen solltest

  • Pfade sind absolut oder beginnen mit ~. Ein relativer Pfad wird abgelehnt, weil der Assistent den Arbeitsordner des Programms nicht kennt.
  • Jede Änderung wird sofort gespeichert. Lehnt das Programm eine Änderung ab, etwa einen Punkt außerhalb der Karte oder einen vergebenen Code, bleibt die Datei, wie sie war, und der Assistent bekommt den Grund.
  • Hat sich die Projektdatei geändert, nachdem der Assistent sie gelesen hat, etwa weil du im Editor einen Posten verschoben hast, schreibt das Programm nichts. Der Assistent bekommt „ hat sich auf der Platte geändert, nachdem es gelesen wurde. Es wurde nichts geschrieben. Lies das Projekt neu und wiederhole die Änderung“ und wiederholt die Änderung mit dem neuen Stand.
  • Positionen stehen in Kartenmillimetern im Kartenmaßstab, y zeigt nach unten. Sieh dir jede Postenposition selbst auf der Karte an. check prüft Abstände, Winkel und Codes gegen die Regeln (Kapitel 8), aber nicht, ob der Posten am richtigen Objekt steht.
  • Postennummern setzt das Programm nur, wenn der Assistent darum bittet. Ändert er danach Strecken oder die Reihenfolge, muss er sie neu setzen lassen. Eine Nummernlage, die für einen Posten oder in einer Bahn festgelegt ist, bleibt dabei stehen.
  • Die automatische Platzierung setzt die Nummer hinter den Kreis, in Verlängerung der Strecke, die zum Posten hinführt. Knickt die Bahn kaum ab, läuft die weiterführende Strecke dort entlang, und die Nummer steht außen an der Spitze des Winkels. Auf Punkt- und Liniensymbolen der Karte steht sie nur, wenn kein freier Platz bleibt; Flächen darf sie überdecken. Gefällt dir die Lage nicht, setzt du sie selbst.
  • Die Nummer steht 0,5 bis 5 mm vom Kreis entfernt (Abstand der Kreislinie zum Nummernfeld, Regel wkb2026.number.gap). Die automatische Platzierung beginnt bei 0,5 mm und rückt in 0,5-mm-Schritten nach außen, bevor sie von der bevorzugten Richtung abweicht. check warnt, wenn ein gespeicherter Abstand außerhalb liegt, etwa bei einer von Hand gesetzten Nummer mit 6 mm.
  • Ändert sich die Reihenfolge einer Bahn, verliert jede Strecke, die jetzt zu einem anderen Bahnpunkt führt, ihre Knickpunkte und ihre Abflaggung. Der Assistent bekommt eine Liste dieser Strecken.
  • Einzel- und Score-Bahnen lassen sich bearbeiten (siehe Score-Bahnen unten). info nennt die Länge von Einzelbahnen; bei einer Score-Bahn nennt es Posten, Punkte und Zeitlimit, und score length misst sie. Mannschafts- und Staffelbahnen lassen sich noch nicht bearbeiten; das Programm sagt das.
  • Die Projektdatei ist einfaches TOML. freemapper-courseplan info <Projekt> zeigt, was der Assistent getan hat, und list controls|courses|specials|classes <Projekt> führt die Einzelheiten auf; map extent <Projekt> und map near <Projekt> --at X,Y --radius MM berichten über die Karte. Alle nehmen --json.

    • Score-Bahnen

    Auf einer Score-Bahn besuchen die Läufer die Posten in beliebiger Reihenfolge innerhalb eines Zeitlimits. Jeder Posten zählt Punkte, und jede angefangene Minute über dem Limit kostet Punkte. Diese Befehle bauen eine solche Bahn; check prüft sie (Abschnitt 8).

    freemapper-courseplan course add halle.courseplan.toml Score45 --kind score --start S1 --finish F1 --time-limit 45
freemapper-courseplan score controls halle.courseplan.toml Score45 31,32,43,54
freemapper-courseplan score link add halle.courseplan.toml Score45 31 54
freemapper-courseplan score settings halle.courseplan.toml --value-max 5 --good-pace 4:10
freemapper-courseplan score course set halle.courseplan.toml Score45 --penalty 6
    • Der Code trägt den Wert: die zweite Ziffer eines zweistelligen Codes, die letzte eines längeren. 43 zählt also 3 Punkte, 54 zählt 4. score controls liest den Wert aus dem Code. Ein Wert, den du nach = schreibst, etwa 43=3, muss dazu passen; weicht er ab, lehnt das Programm ab und rät, den Code zu ändern. score value folgt derselben Regel und repariert deshalb nur einen Wert in der Datei, der nicht mehr zu seinem Code passt. Ein Code ohne Wert, etwa A1, braucht einen: A1=2.
    • Die Werte reichen von 1 bis zum höchsten Wert der Veranstaltung, standardmäßig 5, höchstens 9 (score settings --value-max).
    • Ohne --penalty speichert die Bahn keinen Abzug und nimmt den Standard: den höchsten Postenwert der Bahn, mindestens den höchsten Wert der Veranstaltung, damit sich eine Minute zu viel nie lohnt. Der Standard folgt den Posten. score course set --penalty N speichert eine eigene Zahl, --no-penalty kehrt zum Standard zurück.
    • Wer den Code eines Postens ändert (control code), gibt ihm den Wert des neuen Codes. Ein Code ohne Wert lässt den alten Wert stehen, und check meldet den Unterschied.
    • Eine Verbindung nennt zwei Posten, die der Läufer direkt nacheinander anlaufen muss, in beliebiger Richtung. Wer das nicht tut, wird disqualifiziert. Ein Posten hat höchstens zwei Verbindungen, und Verbindungen dürfen keinen Ring schließen. Ein Posten mit Verbindung bleibt in der Bahn, bis du die Verbindung entfernst (score link remove).
    • score settings schreibt den Abschnitt [score] der Veranstaltung: Wertebereich, die Pace eines guten und eines sehr guten Läufers (Sekunden je Kilometer oder 4:10), die Zielbänder (--good-band 87-93, --very-good-band 95-100, in Prozent), ihre Toleranz (--band-tolerance 3, 0 bis 10 Prozentpunkte), den Anteil schwerer Posten und den Startwert. Vier Abstände in Metern im Gelände regeln, wo Posten stehen (ADR 0072): --value1-min (150 m) ist der kleinste Abstand eines Postens von Start und Ziel, ab dort beginnt Wert 1; --min-gap (100 m, nicht kleiner) der kleinste Abstand zweier Posten; --high-value-gap (200 m, mindestens --min-gap) der kleinste Abstand zweier hochwertiger Posten, also der oberen vier Zehntel der Werte (4 und 5 bei höchstem Wert 5); --max-reach der größte Abstand vom Start. Ohne ihn gilt automatisch ein Viertel der Strecke, die der gute Läufer im Zeitlimit schafft (900 m bei 15 Minuten und 4:10 min/km); --auto-reach kehrt dazu zurück. Ein Abstand ist ein ganzer Wert in Metern.
    • Jeder dieser Befehle nimmt --json und gibt aus, was das gleichnamige MCP-Werkzeug antwortet (add_score_course, set_score_controls, set_control_value, add_score_link, remove_score_link, set_score_settings, set_score_course_details). Der Editor führt dieselben Operationen aus, und Rückgängig nimmt jede zurück.
    • Knicke, Strecken, Postennummern und course controls gehören zu Einzelbahnen; eine Score-Bahn lehnt sie ab. Kategorien, Druckmaßstab, course rename und course remove gelten für beide. Mannschafts- und Staffelbahnen lassen sich noch nicht bearbeiten.
    • Der IOF-XML-Export schreibt auch Score-Bahnen (siehe Export unten). Der Purple-Pen-Export lässt sie weiter aus und sagt es. Der Editor zeichnet Score-Bahnen und hat ein Score-Fenster (siehe „Das Score-Fenster“ im Editor-Kapitel).

    Listen und Auswertungsbogen

    freemapper-courseplan export hall.courseplan.toml --course Score45 --csv score45.csv --sheet score45.md

    --csv schreibt eine Zeile je Posten: code,value,x_mm,y_mm, nach Code geordnet, mit Positionen in Kartenmillimetern im Kartenmaßstab (y zeigt nach unten) und einem Punkt als Dezimaltrenner. --sheet schreibt den Auswertungsbogen als Markdown, ein Text, der sich so gut drucken lässt: das Zeitlimit, den Abzug je angefangene Minute (den gespeicherten oder den Standard), die Regel, dass bei gleicher Punktzahl gewinnt, wer schneller ist, die Pflichtverbindungen mit der Regel, dass disqualifiziert wird, wer eine Verbindung nicht direkt läuft, und eine Tabelle der Posten mit ihren Werten. Beide brauchen --course und lehnen eine Bahn ab, die keine Score-Bahn ist. Eine vorhandene Datei wird ersetzt. Die Werkzeuge heißen export_score_csv und export_score_sheet, mit project, course und path (Endung .csv oder .md). Die Entscheidungen stehen in ADR 0070.

    Vorschläge, Entwurf und Länge

    Diese drei Befehle lesen die Karte und suchen Wege auf einem Raster der Kartensymbole (ohne Höhen). Auf einer großen Karte brauchen sie deshalb einige Sekunden. Start und Ziel müssen außerhalb von Gebäuden und gesperrten Gebieten liegen; sonst meldet das Programm, dass Start oder Ziel nicht erreichbar ist.

    freemapper-courseplan score suggest hall.courseplan.toml --limit 30
freemapper-courseplan score draft hall.courseplan.toml Score45 --time-limit 45
freemapper-courseplan score draft hall.courseplan.toml Score45 --time-limit 45 --apply
freemapper-courseplan score length hall.courseplan.toml Score45
    • score suggest listet Postenplätze, die beste Routenwahl zuerst, jeweils mit Position, Symbolcode des Kartenobjekts, Routenwahl und Schwierigkeit von 0 bis 1, der Zeit vom Start für den guten Läufer und dem Wert, den der Posten bekäme. Es schreibt nichts. --limit setzt die Anzahl (standardmäßig 60, höchstens 200), --min-distance den kleinsten Abstand in Kartenmillimetern (standardmäßig die Einstellung min_gap_m, 100 m im Gelände). Plätze näher als value1_min_m an Start oder Ziel und, mit --course, weiter als die Reichweite vom Start entfernt fallen weg. score draft hält zusätzlich den Abstand hochwertiger Posten ein; check warnt, wenn eine Bahn ihn oder den Mindestabstand unterschreitet. --course NAME nimmt Start und Ziel dieser Score-Bahn (--start und --finish haben weiter Vorrang); ohne die Option gelten der erste Start und das erste Ziel des Events. Plätze in Sperr- und Gefahrengebieten, auf oder in Kartenflächen mit dem Symbol 520, 709 oder 714 und näher als 4 m an einem gesperrten Weg sind ausgeschlossen. Mit --json und über MCP hat jeder Kandidat außerdem einen freien code, der seinen Wert trägt. Er ist null, wenn kein freier Code mehr da ist: Nur die bestplatzierten Kandidaten bekommen einen.
    • score draft wählt aus diesen Plätzen Posten und gibt ihnen Werte und Codes. Der gute Läufer holt dann im Limit standardmäßig 87 bis 93 Prozent aller Punkte, der sehr gute Läufer schafft alle Posten und ist standardmäßig nach 95 bis 100 Prozent des Limits im Ziel. Beide Bänder sind Zielwerte, und ihre Toleranz auch: Ein Ergebnis bis zu 3 Prozentpunkte außerhalb eines Bandes gilt standardmäßig als nahe am Ziel. Bänder und Toleranz sind Einstellungen des Events. Ohne --apply gibt der Befehl den Entwurf nur aus. Mit --apply legt er die Posten an und erstellt die Score-Bahn, oder er ersetzt die Posten einer vorhandenen Score-Bahn und entfernt die Posten, die nur sie nutzte. Eine Bahn anderer Art wird abgelehnt. Im Editor lässt sich die Änderung rückgängig machen.
    • --link "X,Y;X,Y" macht zwei Positionen zu einer Pflichtverbindung; jede muss die Position eines Kandidaten aus score suggest sein, mit einem --limit von mindestens 60 aufgerufen, dem Pool des Entwurfs. Die Option lässt sich für weitere Verbindungen wiederholen.
    • Jeder Läufer landet im Band, nahe am Ziel oder verfehlt. Im Band und nahe am Ziel sind Erfolge: Der Befehl endet mit 0, und bei einem Entwurf nahe am Ziel nennt er die Abweichung, etwa „1,7 Prozentpunkte über dem Band ... innerhalb der Toleranz von 3 Prozentpunkten“. Verfehlt ein Entwurf ein Band über die Toleranz hinaus, endet der Befehl mit 1. Er nennt jedes verfehlte Band mit der Größe der Abweichung und einen Hinweis: ein längeres oder kürzeres Limit, mehr geeignete Plätze, freie Codes (die Postenzahl ist durch den Coderaum begrenzt: erhöhe den höchsten Wert mit score settings --value-max, höchstens 9, oder gib Codes auf der Karte frei), ein schnellerer guter Läufer oder dass diese Eingaben nicht gehen.
    • score length analysiert eine vorhandene Bahn, zum Beispiel nachdem du einen Posten verschoben hast, und meldet dieselben Bänder und Abweichungen und sagt, in welchem der drei Zustände die Bahn liegt. Es ändert die Bahn nie.
    • Dieselben Antworten liefern die Werkzeuge score_suggest, score_draft und score_length; --json gibt sie aus. Der Entwurf ist bei gleichem Projekt bei jedem Lauf derselbe.
    • score reject --at X,Y lehnt einen Standort ab: Du weißt, dass die Stelle nicht passt, etwa ein privater Hof oder eine Ecke, die niemand sieht. Die Position kommt in die Projektdatei (Schlüssel rejected_sites), und score suggest, score draft und die Kandidatenliste des Editors lassen sie von da an aus. Ein Kandidat innerhalb von 3 m am Boden gilt als derselbe Standort. score unreject --at X,Y nimmt die Ablehnung zurück und scheitert, wenn der Standort nicht abgelehnt ist. Ein Posten, der dort schon steht, bleibt. Der Editor hat in der Kandidatentabelle neben "Übernehmen" den Knopf "Ablehnen"; Rückgängig nimmt ihn zurück. Die Werkzeuge heißen reject_site und unreject_site mit project und at, und --json gibt ihre Antwort aus: at, added oder removed und rejected_sites, die Zahl der abgelehnten Standorte. Die Entscheidung steht in ADR 0089.

    Stand: v0.18.1 · Quelle auf GitHub