@onimaxxing/sussy-seeds-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 onimaxxing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+# @onimaxxing/sussy-seeds-mcp
+
+MCP server for Oxygen Not Included seed hunting. Runs the sussy-seeds wasm scanner over stdio so an LLM can compose Builder AST specs and drive scans against the game's real worldgen.
+
+Same scanner powers the browser app at [onimaxxing.com/sussy-seeds](https://onimaxxing.com/sussy-seeds/). Same wasm, same constraint kinds, shared share-URL format so a chat session can hand off to the web app and back.
+
+## Install
+
+### Claude Code
+
+Add to `.mcp.json` (project scope) or `~/.claude/settings.json` (user scope):
+
+```json
+{
+  "mcpServers": {
+    "sussy-seeds": {
+      "command": "npx",
+      "args": ["-y", "@onimaxxing/sussy-seeds-mcp"]
+    }
+  }
+}
+```
+
+Reload MCP servers, then ask the LLM to hunt seeds. The first invocation caches the package under npm's `_npx` cache.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the platform equivalent:
+
+```json
+{
+  "mcpServers": {
+    "sussy-seeds": {
+      "command": "npx",
+      "args": ["-y", "@onimaxxing/sussy-seeds-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop.
+
+### Other MCP clients
+
+Any client that speaks the stdio transport works. Tool schemas are declared via the standard MCP JSON-RPC surface (`tools/list`, `tools/call`). Progress notifications tagged with `_meta.progressToken` are emitted during long JS-tier scans.
+
+## Requirements
+
+Node 20 or newer. No ONI install required; the gambling wasm and the worldgen wasm ship inside the depended-on packages.
+
+## Tools
+
+Grouped by phase of a typical hunt.
+
+### Discovery
+
+Read-only catalogs of ids the LLM composes constraints from. Each takes an optional `coord` and annotates per-world admissibility where the KG can prove it.
+
+- `listClusters({filter?})`, with disambiguation hints for shared-stem labels (`AQU-C` vs `V-AQU-C`)
+- `listWorlds({coord})`, `listWorldsAcrossClusters({query})`
+- `listStoryTraits`, `listMixingCategories`
+- `listGeysers`, `listTraits`, `listBiomes`, `listPois`
+- `listSpawnTags({query?, group?})` paginated critter and plant prefab tags
+- `listConstraintKinds` Builder AST catalog with example payloads
+- `listHelpers` ADVANCED_HELPERS names for preHook / postHook use
+- `listPrefabAdmissibility({coord, prefabId})` point check across a cluster's worlds
+
+### Coord composition
+
+- `buildCoord({formState})`, `parseCoord({coord})`, `describeCoord({coord})`, `freshCoord({clusterPrefix})`
+
+### Admissibility
+
+- `verdictOf({coord, constraint})`, `verdictOfSpec({coord, spec})` microsecond KG-side check for structurally-impossible constraints. Catches things like "Niobium ≤ 4 hexes from home on AQU-C" where the KG placement is rings 7-10 and no seed can match.
+
+### Scanning
+
+JS-tier scans stream progress via `notifications/progress` when the client sends `_meta.progressToken`. Cancellable via the standard JSON-RPC cancel request; server returns the top-K accumulated so far.
+
+- `scan({coord, spec, opts?})` seed range scan, top-K matches. Auto-selects bytecode tier (~1M seeds/sec/core) for require-only summary specs; falls to JS tier for prefer mode or map-tier constraints.
+- `scanUntil({coord, spec, targetHits, opts?})` stops at N matches.
+- `scanSeeds({coord, spec, seeds})` evaluates against an explicit seed list, one row per input including `pass: false`.
+
+`spec.preHook` and `spec.postHook` accept raw JS bodies that run before requires and after prefers respectively. A reserved-identifier guard rejects sources that would shadow the Builder emit's bindings.
+
+### Inspection
+
+- `getSeedSummary({coord, seed})` cluster shape from the wasm summary. Cheap.
+- `getSeedDeep({coord, seed})` full worldgen projection with geyser rates and positions.
+- `describeSeed({coord, seed, deep?})` plain-English narration.
+
+### Sharing
+
+- `shareResults({coord, spec, seeds, scanLimit?, tab?})` encodes the current session, uploads to the sussy-seeds share endpoint (R2 + CDN), returns `https://onimaxxing.com/sussy-seeds/<hash>`. Opening the URL loads the Builder tab with the exact spec, pins the seeds, sets the coord.
+
+### Diagnostics
+
+- `ping()` smoke test.
+- `probeStreaming({steps, delayMs})` emits N progress notifications spaced by delayMs. Use to verify what your MCP client does with the notifications.
+
+## Constraint kinds
+
+Every kind the sussy-seeds Builder tab supports is accepted through the MCP surface. Call `listConstraintKinds` for the catalog with example payloads. Current set:
+
+`world.trait`, `world.geyser`, `world.distToHome`, `world.distTo`, `world.traitCount`, `world.oilWells`, `world.critter`, `world.plant`, `world.spawn`, `world.biomeCount`, `world.marshyTungstenInMagma`, `world.niobiumVolcanoAccess`, `world.sussy`, `world.trash`, `world.asteroidRemix`, `poi.count`, `map.elementMass`, `home.geyserNearStart`, `cluster.geyser`, `cluster.oilWells`, `cluster.critter`, `cluster.plant`, `cluster.sussy`, `cluster.trash`.
+
+## Development
+
+Sources live in the [onimaxxing](https://github.com/tigin-backwards/onimaxxing) monorepo at `packages/sussy-seeds-mcp/`, and reach into `apps/onimaxxing/src/gambling/` for the compile-to-js pipeline and constraint AST.
+
+```
+pnpm install
+pnpm --filter @onimaxxing/sussy-seeds-mcp build
+```
+
+For local Claude Code development, point `.mcp.json` at the built file directly:
+
+```json
+{
+  "mcpServers": {
+    "sussy-seeds": {
+      "command": "node",
+      "args": ["/absolute/path/to/packages/sussy-seeds-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Reload MCP servers on every rebuild.
+
+## License
+
+MIT.