{"id":50791481,"url":"https://github.com/caspervg/dbpf-mcp","last_synced_at":"2026-06-12T11:30:33.639Z","repository":{"id":361638236,"uuid":"1250613246","full_name":"caspervg/dbpf-mcp","owner":"caspervg","description":"Kotlin/Scala MCP server for browsing and exploring SimCity 4 DBPF assets","archived":false,"fork":false,"pushed_at":"2026-05-31T15:03:01.000Z","size":111,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T17:05:00.798Z","etag":null,"topics":["dbpf","exemplar","fsh","maxis","mcp","sc4","sc4paths","simcity"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caspervg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-26T20:03:35.000Z","updated_at":"2026-05-31T15:02:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/caspervg/dbpf-mcp","commit_stats":null,"previous_names":["caspervg/dbpf-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/caspervg/dbpf-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caspervg%2Fdbpf-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caspervg%2Fdbpf-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caspervg%2Fdbpf-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caspervg%2Fdbpf-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caspervg","download_url":"https://codeload.github.com/caspervg/dbpf-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caspervg%2Fdbpf-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dbpf","exemplar","fsh","maxis","mcp","sc4","sc4paths","simcity"],"created_at":"2026-06-12T11:30:32.143Z","updated_at":"2026-06-12T11:30:33.624Z","avatar_url":"https://github.com/caspervg.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dbpf-mcp\n\n`dbpf-mcp` is a Kotlin/JVM Model Context Protocol server for inspecting SimCity 4 DBPF packages. It exposes read-only tools for listing package entries, indexing Plugins folders, decoding common SC4 resource types, and exporting selected decoded resources to text or image files.\n\nThe server currently uses the `backend-scdbpf` adapter and runs over MCP stdio.\n\n## Features\n\n- List and summarize DBPF package entries with stable TGI metadata.\n- Inspect one package for notable entries, SC4 object hints, and recommended next tools.\n- Build a persistent metadata index for a Plugins folder, then search it without rescanning.\n- Decode exemplars and cohorts as semantic JSON with property names, type hints, decoded values, resource keys, and optional parent cohort resolution.\n- Render exemplars and cohorts as canonical SC4 text-exemplar syntax, either in-memory or exported to disk.\n- Decode SC4PATHS entries as JSON or canonical path text, either in-memory or exported to disk.\n- Decode LTEXT, S3D metadata, FSH metadata, image entries, and raw entry previews.\n- Export selected FSH bitmap images as PNG files.\n- Decode individual exemplar property values for quick property interpretation.\n\nExperimental tools:\n\n- `read_keycfg`: heuristic decoder for KEYCFG/TAB-like text resources. It may return noisy fragments and may not reconstruct shortcut records.\n- `read_tab_binary`: structural binary probe for compiled TAB resources. It returns little-endian words and chunks, not a semantic TAB model.\n\n## Project structure\n\n- `core-api`: backend-agnostic models and service contracts.\n- `sc4-semantics`: TGI helpers, property registry loading, and SC4 semantic helpers.\n- `backend-scdbpf`: active scdbpf-backed implementation.\n- `mcp-server`: stdio MCP server entrypoint.\n- `integration-tests`: end-to-end and snapshot-style tests.\n- `vendor/sc4-properties`: Git submodule containing SC4 property registry source data.\n\n## Requirements\n\n- JDK 21 or a compatible Java toolchain.\n- The Gradle wrapper from this repository.\n- A local MCP client that can launch stdio servers.\n\n## Build \u0026 test\n\nFrom the repository root:\n\n```sh\n./gradlew build\n./gradlew test\n```\n\nRun only the MCP server module:\n\n```sh\n./gradlew :mcp-server:run\n```\n\nBuild an installable local distribution:\n\n```sh\n./gradlew :mcp-server:installDist\n```\n\nThe generated launcher is:\n\n```text\nmcp-server/build/install/mcp-server/bin/mcp-server\n```\n\n## Client setup\n\nFor a stdio MCP client, configure the command to point at the installed launcher:\n\n```json\n{\n  \"mcpServers\": {\n    \"dbpf\": {\n      \"command\": \"/absolute/path/to/dbpf-mcp/mcp-server/build/install/mcp-server/bin/mcp-server\"\n    }\n  }\n}\n```\n\nFor quick local development, you can also launch through Gradle:\n\n```json\n{\n  \"mcpServers\": {\n    \"dbpf\": {\n      \"command\": \"/absolute/path/to/dbpf-mcp/gradlew\",\n      \"args\": [\"-p\", \"/absolute/path/to/dbpf-mcp\", \":mcp-server:run\"]\n    }\n  }\n}\n```\n\nThe installed launcher is preferred for day-to-day use because it avoids Gradle startup overhead.\n\n## Basic use\n\nMost tools operate on one DBPF package file, not a Plugins folder. Use `index_plugins` only when you want folder-wide search or cross-package parent cohort lookup.\n\nTypical workflow:\n\n1. Use `index_plugins` with a Plugins folder path, for example `~/Documents/SimCity 4/Plugins`.\n2. Use `search_index` to find candidate entries by TGI, resource kind, exemplar name, object class, or property ID.\n3. Use `inspect_package`, `summarize_package`, or `list_entries` on a specific `.dat`, `.SC4Lot`, `.SC4Model`, or `.SC4Desc` file.\n4. Use focused readers such as `read_exemplar`, `read_cohort`, `read_sc4paths`, `read_fsh`, `read_s3d`, or `read_ltext`.\n5. Use export tools such as `export_exemplar_text`, `export_cohort_text`, `export_sc4paths_text`, `export_sc4paths_json`, or `export_fsh_png` when you want files written to disk.\n\nTGI arguments can be supplied either as one string:\n\n```text\n6534284A-A8434037-0C006800\n```\n\nor as separate `type`, `group`, and `instance` hex values.\n\n## Index cache\n\n`index_plugins` writes persistent JSONL metadata under:\n\n```text\n~/.cache/dbpf-mcp/indexes\n```\n\n`search_index` never recursively scans the folder. If `index_status` reports stale or missing files, run `index_plugins` again.\n\n## Environment variables\n\n- `DBPF_MCP_INDEX_DIR`: overrides the directory used for persistent `index_plugins` JSONL cache files. By default, dbpf-mcp uses Java's `user.home` and appends `.cache/dbpf-mcp/indexes`. On Windows this is typically `C:\\Users\\\u003cyou\u003e\\.cache\\dbpf-mcp\\indexes`; on macOS/Linux this is typically `~/.cache/dbpf-mcp/indexes`.\n- `JAVA_HOME`: selects the JDK used by Gradle and the installed server launcher. Use a JDK 21-compatible installation.\n- `JAVA_OPTS`: optional JVM options used by the installed server launcher.\n- `GRADLE_OPTS`: optional JVM options used when launching through Gradle.\n\n## Limitations\n\n- This is still in development. Tool output schemas may still evolve.\n- Folder-wide scanning happens only through `index_plugins`; other tools expect one DBPF package path.\n- Cross-package parent cohort resolution requires a current Plugins index and is limited to entries present in that index.\n- S3D support reports model metadata, mesh group summaries, materials, and animation metadata; it does not export full geometry.\n- `read_keycfg` and `read_tab_binary` are not finished.\n\n## Common commands\n\n```sh\n./gradlew build\n./gradlew test\n./gradlew :sc4-semantics:test\n./gradlew :integration-tests:test\n./gradlew :mcp-server:run\n./gradlew :mcp-server:installDist\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaspervg%2Fdbpf-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaspervg%2Fdbpf-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaspervg%2Fdbpf-mcp/lists"}