Teskooano
Play

Connect an agent (MCP)

Teskooano runs a Model Context Protocol server at https://teskooano.space/mcp. An agent connected to it can read the catalogue, build systems in real units, save them to your account, check them for physical problems and run the simulator’s N-body integrator on them.

Connecting

Add the server URL as a custom connector (in Claude: Settings → Connectors) or in your MCP client’s config. The first time, it sends you to sign in with GitHub, Google or Steam and asks which permissions to grant:

Scope Allows
systems:read Reading the catalogue and your systems, analysing and simulating them
systems:write Creating, editing and deleting your systems

Without systems:write, the write tools answer with an error asking you to reconnect. Remove the connector in your client to disconnect.

Referring to systems

Tools that take a ref accept either a catalogue system, as catalogue:<slug> such as catalogue:sol, or the id of one of your saved systems. Catalogue systems are read-only; system_clone makes you a copy.

Tools

Tool Scope Does
whoami read Who you’re signed in as and the scopes granted
catalogue_list read The published catalogue systems, each with locked if your plan can’t open it yet
systems_list read Your saved systems, 50 at a time
system_get read A system: a summary table, or the whole file with detail: "file"; version reads an earlier one
body_get read One body: mass, radius, orbit, parent and what orbits it
system_open_link read A link that opens a catalogue system in the simulator
system_analyse read Physical checks: see Findings
system_simulate read Runs the integrator; returns collisions, escapes and orbit drift
system_compare read What differs between two systems, body by body
system_versions read A system’s versions, newest first, with what changed
system_generate write A procedurally generated system from a seed, saved to your account
system_create write A new system with one star
system_import write Saves a system file you supply
system_clone write Copies a catalogue or saved system to your account
system_edit write Applies builder operations in one step, with a note
system_restore write Makes an earlier version current again, as a new version
system_update_from_source write Brings a copy up to its original’s current version
system_update write Renames a system or changes its description
system_delete write Deletes one of your systems

Each user can keep 100 systems of up to 1 MB each. Edits carry the system’s revision; pass it back as expectedRevision and an edit made against an older copy is refused rather than overwriting someone’s change.

Versions and copies

Every edit that changes a system’s bodies makes a new version; renames don’t. Catalogue systems keep every version and saved systems their last 20. system_versions lists them and system_get with version reads one.

A copy made with system_clone remembers its original and the original’s version, as sourceId and sourceVersion. When the original changes, for example when I fix a catalogue system, the copy’s sourceLatestVersion goes above its sourceVersion. system_compare shows what differs, and system_update_from_source replaces the copy’s bodies with the original’s, keeping the copy’s name. The copy’s own edits stay in its versions, so system_restore brings them back.

Building a system

system_create takes a name and a star. system_edit then takes a list of operations, applied in order; if one fails, none are saved and the error names it.

Units are the ones astronomers publish in:

  • Mass: { "earth": 1 }, { "jupiter": 0.3 } or { "sun": 1.1 }
  • Radius: the same units, or { "km": 1188 }
  • Orbits: semiMajorAxis_au or period_days, plus eccentricity, inclination_deg, longitudeOfAscendingNode_deg, argumentOfPeriapsis_deg and meanAnomaly_deg. Given a period, the builder works out the axis from the masses with Kepler’s third law, so a transit period from a paper goes in as published.
  • Stars: a spectralType such as "G2V", "M5.5V", "K0III", "DA2" (a white dwarf) or "L7.5" (a brown dwarf), temperature_k, and optionally luminosity_lsun (otherwise it follows from the radius and temperature). The kind of star follows from the type and the mass.
Operation Does
add_body Adds a planet, dwarf planet, gas giant, moon, asteroid or comet to a parent
add_star Adds a star: see below
update_body Changes a body’s name, mass, radius, temperature or albedo
set_orbit Changes some of a body’s orbit, or moves it to a new parent
remove_body Removes a body and everything that orbits it
rename Renames the system

Binary and multiple stars

add_star without a parentId pairs the new star with the system’s star. Its orbit is the pair’s relative orbit: semiMajorAxis_au is their separation, or give period_days. The builder adds a barycenter body as the root, puts both stars on opposite sides of it on mass-weighted orbits, and keeps them balanced if you later change either mass. Planets that orbit both stars (circumbinary, like Kepler-16 b) use the barycenter as their parentId. A third star can orbit the barycenter, or one star, with a parentId.

For example, Kepler-16 is:

[
  {
    "op": "add_star",
    "name": "Kepler-16 B",
    "spectralType": "M4V",
    "mass": { "sun": 0.20255 },
    "radius": { "sun": 0.22623 },
    "temperature_k": 3311,
    "orbit": { "period_days": 41.079, "eccentricity": 0.15944 }
  },
  {
    "op": "add_body",
    "name": "Kepler-16 (AB) b",
    "type": "GAS_GIANT",
    "parentId": "barycenter",
    "mass": { "jupiter": 0.333 },
    "radius": { "jupiter": 0.7538 },
    "orbit": { "period_days": 228.776, "eccentricity": 0.0069 }
  }
]

How orbits are placed

Each body’s elements describe the orbit of its subsystem (the body and everything orbiting it) about its parent, the way they are published. A planet with a large moon has its own centre offset by the moon’s share, and the whole system’s centre of mass sits at rest at the origin, so systems don’t drift.

Findings

system_analyse returns findings with a severity: critical (the system can’t work as given), warning (likely to change under simulation) or info (worth knowing).

Code Means
missing_parent A body’s parent isn’t in the system
unbound A body moves too fast to stay with its parent
loosely_bound Bound, but only just
outside_hill_sphere It orbits beyond where its parent’s gravity wins over the star’s
inside_roche_limit Tides would pull it apart
orbits_cross Two paths come within reach of each other at their nodes
orbits_overlap Their distances overlap but the paths stay apart, as Pluto’s and Neptune’s do
close_orbits Neighbours closer than about 10 mutual Hill radii (warning below 7 with three or more bodies)
resonance Periods near a small whole-number ratio, which can keep close orbits stable
habitable_zone Where liquid water could be on a surface, from the star’s light and temperature
binary_stability For two stars, the widest stable orbit about each star and the closest about both

The habitable zone follows Kopparapu et al. (2014), from the runaway greenhouse to the maximum greenhouse limits, and takes the star’s temperature into account. Binary stability follows Holman & Wiegert (1999). Spacing uses the Chambers (1996) and Smith & Lissauer (2009) results: well spaced systems are 10 or more mutual Hill radii apart, but resonant chains such as TRAPPIST-1 are stable closer in, so treat those warnings as a prompt to simulate.

Simulating

system_simulate runs up to 1,000 years, within 10 million body-steps (it reports truncated: true if the budget runs out first). It returns collisions, bodies that left their parent, and each orbit’s semi-major axis and eccentricity at the start and end, most changed first. Ask for up to 200 samples to get positions, in AU, along the way.

The core systems

The catalogue starts from real systems built and checked with these tools: Sol, Alpha Centauri, TRAPPIST-1, Kepler-16 and HD 189733. Send corrections to @teskooano on Mastodon.

Original