dsh-unreal-mcp

Unofficial DeepSeek Harness Bundle for Unreal Engine 5.8's official Unreal MCP
server.

The Bundle is a thin UE adapter. It reuses Unreal's
ModelContextProtocol, ToolsetRegistry, and AllToolsets, and mounts the MCP
Client already supplied by DeepSeek Harness. It does not include Unreal Engine
code, add a UE .uplugin, fork DSH, or implement a general-purpose MCP client.

Scope

This project aims to bring DSH's UE adapter capabilities toward the same
practical boundary as Epic's Claude Code integration:

Claude Code + Epic UE plugin  ->  Unreal MCP server
DSH + dsh-unreal-mcp          ->  Unreal MCP server

It owns Bundle packaging, Unreal endpoint configuration, .uproject and UE
source context, Unreal Skills, read-only diagnostics, UE workflow coverage, and
adapter-level compatibility evidence.

It does not own DSH's general context management, Agent Loop, model behavior,
sessions, approvals, tool scheduling, retries, or the generic MCP protocol
implementation. A problem reproducible with a non-Unreal MCP server should be
reduced and reported upstream instead of fixed here as UE-specific behavior.

Capabilities

The Bundle provides:

• a Cordis plugin managed by DSH's load/unload lifecycle;
• three bundled Unreal Skills registered through ctx.skills;
• per-session .uproject and UE source-tree detection;
• concise Unreal context routed through ctx.systemPrompt.context();
• one loopback-only endpoint setting shared by the context and MCP Client row;
• a read-only diagnostic for connection, Tool Search, and ToolsetRegistry;
• DSH-specific adaptations of Epic's MIT-licensed Unreal Skill guidance.

The bundled Skills are:

• unreal-mcp for discovering and invoking existing Unreal Editor Toolsets;
• create-toolset for authoring AI-callable C++ or Python Toolsets;
• unreal-skill for authoring UE Agent Skills registered inside the Editor.

The last item is distinct from a DSH harness Skill: it guides creation of
UAgentSkill classes or project-specific Skill assets managed by Unreal.

Repository tests cover the package, Skill, context, endpoint validation, and
plugin lifecycle. Unreal MCP has editor-level privileges, so mutating tasks must
use a disposable project with a tested recovery point and retain matching tool
results and final Editor state as evidence.

Prerequisites

• Unreal Engine 5.8 with ModelContextProtocol and AllToolsets enabled
• DeepSeek Harness with Bundle and plugin APIs compatible with 0.1.1-rc.2
• Node.js 20 or newer and pnpm available to dsh plugin
• a disposable Unreal test project

The recorded compatibility configuration is UE 5.8.1, DSH 0.1.1-rc.2,
@deepseek-ai/dsh-mcp-client 0.1.1-rc.2, Node.js 20/22/24, and macOS arm64.

Build and verify

npm ci
npm run check

npm run check compiles dist/, runs the Bundle tests, checks the package
allowlist and executable bit, installs the generated tarball into a clean npm
project, and exercises the installed Skill/context lifecycle.

Install into a DSH Profile

From a built checkout:

dsh plugin --profile web add /absolute/path/to/dsh-unreal-mcp

For a reviewed tarball:

npm pack
dsh plugin --profile web add /absolute/path/to/dsh-unreal-mcp-0.1.0.tgz

From npm:

dsh plugin --profile web add dsh-unreal-mcp

One DSH command installs the Bundle layer. Its Cordis patch loads this package
and configures DSH's in-box @deepseek-ai/dsh-mcp-client for the Unreal MCP
endpoint; users do not copy a Skill or edit DSH source.

An npm tarball contains prebuilt dist/ and installs without running project
code. A direct GitHub install builds through prepare; pnpm 10+ may require the
user to allow that package build explicitly, so releases should prefer npm or a
reviewed tarball.

Connect Unreal

Enable ModelContextProtocol and AllToolsets, then run this in the Unreal
Editor console:

ModelContextProtocol.StartServer 8000

A successful Output Log contains:

Created new HttpListener on 127.0.0.1:8000

Start DSH from the Unreal project directory:

dsh --profile web

The configured endpoint is http://127.0.0.1:8000/mcp. An optional
DSH_UNREAL_MCP_TIMEOUT_MS changes the MCP call timeout. Source engine
checkouts can provide DSH_UNREAL_ENGINE_ROOT; game projects are found by
walking upward from each session's working directory.

See setup.md for persistent startup and
operations.md for troubleshooting.

Diagnose the live connection

npm run diagnose -- --endpoint=http://127.0.0.1:8000/mcp \
--cwd="/absolute/path/to/MyGame/Content"

The diagnostic is read-only. It performs MCP initialization, verifies
list_toolsets/describe_toolset/call_tool, and confirms Unreal returns a
non-empty toolset catalog. It reports separate errors for a missing project,
an unreachable endpoint, missing Tool Search meta-tools, and an empty catalog.

Uninstall

dsh plugin --profile web remove dsh-unreal-mcp

The Bundle plugin, its context and Skill provider, and its configured MCP row
are removed from that Profile together.

Safety and evidence

Unreal MCP has editor-level privileges and some toolsets can execute Python.
The bundled Skill tells the agent to issue UE calls sequentially, require
explicit user authorization before mutations, and inspect UE state before
retrying a non-idempotent operation. Enforcement remains the responsibility of
DSH and the execution environment; this Bundle does not add a generic approval,
scheduler, sandbox, or retry subsystem.

A final answer is not proof by itself: release claims require matching Unreal
tool results and final Editor state.

Security

Report vulnerabilities according to SECURITY.md.

License

Project-original code and documentation are MIT licensed. Adapted Epic Skill
material retains Epic's MIT notice in
EPIC-UNREAL-SKILLS-MIT.txt. Unreal Engine
and its plugins remain governed by Epic's applicable terms. See
THIRD_PARTY_NOTICES.md.