npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

darkest-dungeon-mcp

v1.0.0-beta.1

Published

Read-only MCP server for Darkest Dungeon 1 save data and gameplay knowledge

Readme

Darkest Dungeon MCP

A read-only Model Context Protocol (MCP) server for inspecting Darkest Dungeon 1 save data and retrieving verified gameplay knowledge.

The server decodes copied save files into a temporary directory, validates the decoded JSON, and exposes normalized campaign data without modifying the original saves. It also includes curated knowledge for curios, classes, combat, trinkets, camping skills, quirk treatment, and building-upgrade priorities.

This is an unofficial fan project. It is not affiliated with, endorsed by, or sponsored by Red Hook Studios or the Official Darkest Dungeon Wiki.

Requirements

  • Node.js 20.12 or later
  • For live saves: Java through PATH, JAVA_HOME, or --java, plus DDSaveEditor.jar
  • A PC installation of Darkest Dungeon 1 for official localization, building and trinket definitions, combat skill details, hero progression and quest restrictions, and quirk definitions

Installation

Use the pinned beta package [email protected] with npx. You do not need to clone this repository or build TypeScript. The first launch downloads the package and its dependencies from npm.

Install Node.js and Java, download DDSaveEditor.jar from its release page, then configure a client that supports local stdio MCP servers. Replace the profile, game, and JAR paths below with your own absolute paths. The following is a Windows example using the common mcpServers format:

{
  "mcpServers": {
    "darkest-dungeon": {
      "command": "cmd",
      "args": [
        "/c", "npx", "-y", "[email protected]",
        "--save-dir",
        "C:/path/to/Steam/userdata/STEAM_USER_ID/262060/remote/profile_0",
        "--game-dir",
        "C:/path/to/Steam/steamapps/common/DarkestDungeon",
        "--decoder-jar",
        "C:/absolute/path/to/DDSaveEditor.jar"
      ]
    }
  }
}

Codex uses TOML instead of the JSON wrapper. Add this to ~/.codex/config.toml for a user-level installation:

[mcp_servers.darkest_dungeon]
command = "cmd"
args = [
  "/c", "npx", "-y", "[email protected]",
  "--save-dir", "C:/path/to/profile_0",
  "--game-dir", "C:/path/to/DarkestDungeon",
  "--decoder-jar", "C:/absolute/path/to/DDSaveEditor.jar",
]
startup_timeout_sec = 120
tool_timeout_sec = 120

On macOS/Linux, use command = "npx" (or JSON "command": "npx") and remove the initial "/c", "npx" arguments. Replace Windows paths with paths accessible to the client process. The beta's clean-install test has been verified on Windows with Node.js 22; other platforms are not yet verified.

Restart the client after saving its configuration, then inspect its MCP server list or ask it to call get_game_state. See MCP client configuration for exact locations, commands, and troubleshooting instructions for Codex, Claude Code, Claude Desktop, Google Antigravity, OpenClaw, and generic stdio clients.

--save-dir selects the live profile. Without it, the server uses the checked-in decoded samples. --game-dir enables official localized names plus verified building upgrades, trinket metadata and filters, combat skill details, hero resolve levels, quest eligibility, and quirk analysis. The original profile remains untouched: supported save files are copied to a temporary directory before decoding.

For a demo without Java or a game installation, omit the three path options. Ask the client to call refresh_game_state and check that snapshot.source is sample. For your own campaign, supply --save-dir and confirm it is live. The server runs locally, but tool results are passed to your MCP client and may be sent to its AI provider. npm installation does not provide an AI subscription.

To update, replace the pinned version in the client configuration and restart the server. Keep the previous version string if you need to revert.

Server options

The stdio entrypoint accepts configuration directly and does not require a particular working directory:

npx -y [email protected] --save-dir "C:\path\to\profile_0" --game-dir "C:\path\to\DarkestDungeon" --decoder-jar "C:\path\to\DDSaveEditor.jar"

Available options are --env-file, --save-dir, --game-dir, --decoder-jar, and --java. Command-line options take precedence over process environment variables, which take precedence over an optional .env next to the installed package. Java is discovered through PATH or JAVA_HOME when --java is omitted.

MCP tools

| Tool | Purpose | | --- | --- | | refresh_game_state | Reload the shared read-only save snapshot before a new analysis when the campaign has changed. | | get_game_state | Return a combined campaign summary with localized estate resources, class counts, dungeon quest counts, and built-district names. | | list_building_upgrades | List building upgrades and costs with localized building, tree, and heirloom names. | | recommend_quirk_management | Separate negative-quirk removals from positive-quirk lock guidance with priorities, lock capacity, evidence, and localized quirk text. | | list_heroes | Filter heroes by class, roster status, stress, party availability, and optional quest eligibility; localize class names with language. | | get_hero | Return one hero with localized class, combat-skill, equipped-trinket, quirk, disease, affliction, and virtue names, resolve level, availability, optional quest eligibility, and town activity. | | compare_heroes | Compare 2–8 heroes using localized class, skill, and risky-quirk names plus objective readiness, equipment, skill-position, and curated quirk-risk evidence. | | list_quests | Filter available quests with localized titles, objectives, regions, lengths, and reward names. | | get_quest | Return one quest by ID with localized official quest and reward text. | | list_trinkets | Query up to limit trinkets across storage, heroes, and stores by ID, localized name, hero class eligibility, or rarity; class and rarity filters require DD_GAME_DIR. | | recommend_trinkets | Recommend optimal trinkets for a hero or class, or match candidate heroes for a specific trinket based on estate ownership, tier rankings, and synergies. | | plan_expedition | Build a quest briefing with verified eligibility, role pools, provisions, camping, and tactical guidance. | | recommend_building_upgrades | Rank estate upgrades using current heirlooms, verified costs, exchange feasibility, and curated priorities. | | query_classes | Query verified class guidance with official class, skill, and synergy names localized from the installed game. | | query_combat | Query verified region and enemy guidance by name, region, threat type, or priority. | | search_curios | Search verified curios by ID, localized name, alias, or region. | | get_curio_advice | Return item-aware interaction advice and warnings with localized curio names. |

Live save tools reuse one read-only snapshot for up to two minutes so that a multi-tool analysis observes a consistent campaign state and does not repeatedly decode the profile. Call refresh_game_state when the user reports an in-game change and a fresh snapshot is needed. Refreshing only replaces the server's in-memory snapshot; it never writes to the game profile. Sample mode uses a stable snapshot until explicitly refreshed.

Localization

Tools with a language input accept en, fr, de, es, pt-BR, ru, pl, cs, it, zh-CN, ja, and ko; the default is en. These codes map to the language IDs verified in the installed Darkest Dungeon 1 string tables. Official display names are returned only when the corresponding game string exists; otherwise the localized field is null or the documented stable-ID fallback is used. Stable internal IDs remain available in either case. Curated strategy, priority, and policy prose remains English source material for the MCP client to summarize in the user's language.

Curio coverage includes shared curios, Ruins, Warrens, Weald, Cove, Courtyard, Farmstead, Darkest Dungeon, Old Road, and relevant Hamlet quests. Retired curios that are no longer used by the game are intentionally excluded. search_curios and get_curio_advice resolve official curio names from DD_GAME_DIR; availableItems accepts internal IDs or official display names in any supported language. The curated knowledge set retains search aliases and language-neutral interaction outcomes and advice.

Class knowledge covers all 18 playable Darkest Dungeon 1 classes and all 126 combat skills. query_classes resolves official class and skill names from DD_GAME_DIR; the knowledge set retains only search aliases and language-neutral strategy guidance. Skill guidance uses internal IDs verified against the installed game definitions and describes use cases, synergies, and cautions without duplicating exact position or target data.

list_heroes, get_hero, and compare_heroes accept language. When DD_GAME_DIR is configured, heroClassName, combat skill name, camping skill name, equipped trinket name, quirks[].name, afflictionName, and virtueName values come directly from the installed game's localization files; stable internal IDs remain available alongside them. In get_hero, equippedTrinkets also includes official rarity, heroClassRequirements, class compatibility isUsableByHeroClass, and stat effects. campingSkillDetails provides official skill names, respite point costs, nighttime ambush prevention flags, disease cure flags, and categorized utility. In compare_heroes, quirkTreatmentAnalysis.risk.riskyQuirks entries also include localized names.

list_trinkets accepts id, query, location, heroClass, rarity, limit (default 50, maximum 100), and language. It resolves official trinket names, rarities, hero class requirements (with localized class names), and stat buff/debuff effects from DD_GAME_DIR, including base-game, official DLC, and backer trinkets. Filtering by heroClass or rarity returns an explicit configuration error when installed game definitions are unavailable instead of returning an unverifiable result. Gold-priced trinkets use price with shardPrice: null; Color of Madness trinkets use shardPrice with price: null, preserving the game's actual purchase currency instead of treating shards as gold.

recommend_trinkets evaluates equipment options for a hero (heroId), a class (heroClass), or a specific item (trinketId). It matches curated S/A/B/situational tier ratings, class-specific synergies, and usage cautions against current estate ownership (in_storage, equipped_by_self, equipped_by_other, in_store, or not_owned). Pass exactly one of heroId, heroClass, or trinketId. By default, store-only items are not treated as owned; they are exposed with isAvailableForPurchase when onlyOwned is false. When given trinketId, it returns candidate roster heroes ranked by suitability. Each candidate includes current stress and party-selection availability, and available candidates are ranked ahead of heroes blocked by a raid or town activity.

plan_expedition prepares a comprehensive expedition briefing (dossier) for a target quest or dungeon region (questId, dungeon, difficulty, preferredHeroIds, and language). It integrates strict eligibility pruning (resolve-level restrictions and party-selection availability), explicit separation of unverifiable eligibility, stress cautions, and class-knowledge-backed candidate pools across 4 functional roles (Frontline DPS, Control/Disruptor, Support/Stress Healer, and Primary Healer), curated class-compatible trinket matches, automated supply provision calculations with itemized gold costs based on dungeon length and regional curio cleansing needs, nighttime ambush prevention and camping strategy analysis (campingStrategy with 12-point respite plan and ambush prevention providers), and target boss / regional combat tactics. Heroes whose quest eligibility cannot be verified are returned separately under unverifiedHeroes and are not included in the role pools.

recommend_building_upgrades accepts language and analyzes the estate's building upgrades and current heirloom resources (Busts, Portraits, Deeds, Crests). It evaluates strategic priority tiers (S, A, B, C), separates high-priority core targets (Blacksmith, Guild, Stage Coach) from immediately affordable alternatives, calculates heirloom shortages, simulates Heirloom Exchange feasibility with surplus currencies, and recommends targeted farming dungeons (e.g. Weald for Deeds, Warrens for Portraits).

recommend_quirk_management accepts independent minimumNegativePriority and minimumPositivePriority filters plus includeUnrated, heroId, language, and limit. It separates negativeRemovals from positiveQuirks and reports each positive quirk as lock_positive, keep_locked, do_not_prioritize, or unrated. The result also reports the verified three-slot positive-lock capacity, current usage, remaining slots, definition coverage, game effects, cautions, and evidence sources. The checked-in policy currently contains 40 negative-removal rules and 16 general or conditional positive-lock rules. Official names and descriptions are localized; priorities, reasons, cautions, and policy text remain English editorial source material for the client to summarize in the user's language.

Town-facing and campaign tools accept language and resolve official building, activity, district, upgrade-tree, heirloom, estate resource, class count, and dungeon quest count names from DD_GAME_DIR. Stable IDs are retained alongside localized display names.

Combat knowledge covers Ruins, Warrens, Weald, Cove, Courtyard (Crimson Court), Farmstead (Color of Madness), their region-specific enemies, shared roaming enemies, and key bosses / minibosses (Necromancer, Prophet, Swine Prince, Hag, Siren, Drowned Crew, Collector, Shambler, Crocodilian, and The Miller). query_combat accepts query, region, threat, priority, scope, and language filters. Region display names and localized-name search come from the installed game's localization files when DD_GAME_DIR is configured. Enemy and dangerous-action names use the same localization source; English strategy guidance remains language-neutral source material for the client to summarize in the user's language. The guidance describes qualitative priorities, dangerous actions, and counters. It covers the listed base and DLC regions and curated bosses, but does not provide live turn state or exact enemy stats.

Quirk management combines the current roster, installed game definitions, and a conservative editorial policy. Negative rules focus on verified high-impact penalties and forced interactions. Positive rules prioritize broadly applicable speed, accuracy, defense, and opening-round effects while explicitly identifying lower-value town or camping effects. Uncurated positive quirks can be returned as unrated; special non-replaceable quirks are never curated as Sanitarium lock targets. Results are guidance, not an absolute or exhaustive treatment order. The evidence and priority policy is documented in docs/QUIRK_MANAGEMENT_POLICY.md.

Combat skill levels combine per-hero purchases from persist.upgrades.json with installed hero upgrade definitions. The raw values under selected_combat_skills only identify selection data and are never reported as levels. Without --game-dir, get_hero returns selected skills with level: null rather than guessing.

With a configured game installation, combat skill details also include the party positions where each skill can be used, its target side and positions, whether it targets one, a group, or a random unit, and any forward or backward movement. Position 1 is the frontmost position and position 4 is the rearmost position for both sides. get_hero also summarizes the selected loadout as objective per-position coverage, including positions where every selected skill works and positions with the highest skill count. These fields do not apply an editorial viability threshold.

Hero resolve levels are derived from the thresholds in the configured game installation. Hero results also report whether each hero can be newly selected for a party and list concrete blockers such as an existing raid or town assignment. Pass a questId to list_heroes or get_hero to apply the installed game's resolve-level restriction for that quest; eligibleOnly can then restrict list_heroes to eligible heroes.

Knowledge data and attribution

Curios, classes, combat, trinkets, camping skills, quirk treatment, and building-upgrade priorities live under data/knowledge. The curio, class, and combat guidance is adapted from the Official Darkest Dungeon Wiki, and its records retain source URLs and verification dates. Other knowledge files contain verified game identifiers and explicitly editorial recommendation data.

The wiki material was summarized, normalized into a machine-readable schema, reorganized by interaction, and supplemented with clearly marked recommendation metadata. No wiki images are included. The adapted knowledge data is distributed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International, matching the source license. Reuse of that data must preserve attribution, remain noncommercial, indicate changes, and use the same license for adaptations.

See LICENSE.md for the exact licensing scope. Source code and wiki-derived knowledge data are licensed separately.

Disclaimer

Darkest Dungeon and related names and trademarks belong to their respective owners. This software is provided without warranty. Back up save data before using third-party tools, even though this server is designed to be read-only.

For source development and testing, see the contributor guide.