{"_id":"@alemdarlabs/sage-mcp","_rev":"8-b819650a7a8be6d04f9d8c9c9de162dd","name":"@alemdarlabs/sage-mcp","dist-tags":{"latest":"0.1.13"},"versions":{"0.1.0":{"name":"@alemdarlabs/sage-mcp","version":"0.1.0","license":"UNLICENSED","_id":"@alemdarlabs/sage-mcp@0.1.0","maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"sage":"npm/bin/sage.js"},"cpu":["x64","arm64"],"dist":{"shasum":"8e0cfe41c871d3d94360e5303cc1b655c9f7c27a","tarball":"https://registry.npmjs.org/@alemdarlabs/sage-mcp/-/sage-mcp-0.1.0.tgz","fileCount":13,"integrity":"sha512-3eX2O71F5Cjcl0wmqtttmR9SOiUiCVXuFpBFbtqyJKq6WNIZAG+iYaU9sGNqYaeuFFLooc4YqbS1SZy6RDi+kA==","signatures":[{"sig":"MEYCIQD2dnJlb25ryJ93n5ksnvLrRZ4Q12keSireUKBcDKyd3wIhAPrHHS4n1gIZjhoPGWlfgJNtepBWBT1qk4mfVx1LoOiV","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44772},"type":"commonjs","engines":{"node":">=18"},"gitHead":"c52ca0a9dbaa64b8b884d742cdfa0c17c56a0106","scripts":{"test":"node npm/tests/cli-smoke.test.js","postinstall":"node npm/scripts/postinstall.js","test:global":"node npm/tests/global-install-smoke.test.js","release:check":"node npm/scripts/release-check.js","package:assets":"node npm/scripts/package-assets.js"},"_npmUser":{"name":"alemdarlabs","email":"admin@alemdarlabs.com"},"repository":{"url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Sage MCP server for Unreal Engine","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sage-mcp_0.1.0_1780603735521_0.16695257822911658","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@alemdarlabs/sage-mcp","version":"0.1.1","license":"UNLICENSED","_id":"@alemdarlabs/sage-mcp@0.1.1","maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"sage":"npm/bin/sage.js"},"cpu":["x64","arm64"],"dist":{"shasum":"98e2fee47ad4839ea4fc3e3c619fae7bf0bb0ee9","tarball":"https://registry.npmjs.org/@alemdarlabs/sage-mcp/-/sage-mcp-0.1.1.tgz","fileCount":13,"integrity":"sha512-LQ02ysTcKiMvKE6dKVXgjsMpSO1r6tcGKlmbiLi5TO0OxlRYKABdpZjOn/6QwMbf5Gpd14T4qnYJPoH48ZE0AQ==","signatures":[{"sig":"MEYCIQC6LyIiRbofy/9JzBNLI64rydfblvH0Kzn5+dR/4/PL0wIhAL/ISrQeKFsrGnpAevVYQII5HufcBu2PsZGz/U+8xG/+","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51700},"type":"commonjs","engines":{"node":">=18"},"gitHead":"3d973a5b1331ec8639ef2f2af67bfc325bfaa6be","scripts":{"test":"node npm/tests/cli-smoke.test.js","postinstall":"node npm/scripts/postinstall.js","test:global":"node npm/tests/global-install-smoke.test.js","release:check":"node npm/scripts/release-check.js","package:assets":"node npm/scripts/package-assets.js"},"_npmUser":{"name":"alemdarlabs","email":"admin@alemdarlabs.com"},"repository":{"url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Sage MCP server for Unreal Engine","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sage-mcp_0.1.1_1780611979719_0.5733549171838999","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@alemdarlabs/sage-mcp","version":"0.1.2","license":"UNLICENSED","_id":"@alemdarlabs/sage-mcp@0.1.2","maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"sage":"npm/bin/sage.js"},"cpu":["x64","arm64"],"dist":{"shasum":"08642f3dccea5fc6f349f2448f1e78c87ad425d3","tarball":"https://registry.npmjs.org/@alemdarlabs/sage-mcp/-/sage-mcp-0.1.2.tgz","fileCount":14,"integrity":"sha512-Vxwa9cqHwNkzfZjb5ojRnmLm8N7wNg0tj60u8eoPcb9Tt4eSf5UZZKkBVo7r9YkYE8Bduf+xS3sftst0w6I+BA==","signatures":[{"sig":"MEQCIHzCTA0taSf0hit0ScB50jbrYMRaaf/Brlp6Dy7vcBFuAiBhEJNoYJNLjC/74+bTGKqEHruxJV3MK5N1u/q/jxH4RQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62885},"type":"commonjs","engines":{"node":">=18"},"gitHead":"162d5fcb52748f8baa26da18347202b2b7d6b4b4","scripts":{"test":"node npm/tests/cli-smoke.test.js","postinstall":"node npm/scripts/postinstall.js","test:global":"node npm/tests/global-install-smoke.test.js","release:check":"node npm/scripts/release-check.js","package:assets":"node npm/scripts/package-assets.js"},"_npmUser":{"name":"alemdarlabs","email":"admin@alemdarlabs.com"},"repository":{"url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Sage MCP server for Unreal Engine","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sage-mcp_0.1.2_1780614096922_0.9992364322799892","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@alemdarlabs/sage-mcp","version":"0.1.3","license":"UNLICENSED","_id":"@alemdarlabs/sage-mcp@0.1.3","maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"sage":"npm/bin/sage.js"},"cpu":["x64","arm64"],"dist":{"shasum":"a5528bf1d84a11220f838b927d2edb225c58cbac","tarball":"https://registry.npmjs.org/@alemdarlabs/sage-mcp/-/sage-mcp-0.1.3.tgz","fileCount":14,"integrity":"sha512-eR1t89PJz9Rz95HtFfCiW0h8deTq9ReVNpxZz+8LEbKc1ufPJViwW+mmrm6rrmsl7EILb1HbE8A+fFPc9qXpQg==","signatures":[{"sig":"MEQCIE7qmSAu3ouKK4/Quxjv8ZvXsNIbi+WET475HEJGDM4vAiBNVM7fCMoYdmZOq4fX167ounB8IeVyn7/Vn1m7ZrAZ+g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":63389},"type":"commonjs","engines":{"node":">=18"},"gitHead":"56337b0e9f910d0fc42bd7c78fc8d4903e3088b9","scripts":{"test":"node npm/tests/cli-smoke.test.js","postinstall":"node npm/scripts/postinstall.js","test:global":"node npm/tests/global-install-smoke.test.js","release:check":"node npm/scripts/release-check.js","package:assets":"node npm/scripts/package-assets.js"},"_npmUser":{"name":"alemdarlabs","email":"admin@alemdarlabs.com"},"repository":{"url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Sage MCP server for Unreal Engine","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sage-mcp_0.1.3_1780615206568_0.3357816575385084","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@alemdarlabs/sage-mcp","version":"0.1.4","license":"UNLICENSED","_id":"@alemdarlabs/sage-mcp@0.1.4","maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"sage":"npm/bin/sage.js"},"cpu":["x64","arm64"],"dist":{"shasum":"dc1c1b0c4277aea9fa2d3d0086d9bd907cebbb35","tarball":"https://registry.npmjs.org/@alemdarlabs/sage-mcp/-/sage-mcp-0.1.4.tgz","fileCount":14,"integrity":"sha512-vNTvHPIQ9PzRMTVqcBj8nRAzORR/FJVoOiHcdBdBjdYgRoA2Ug924J6DS2Fi+oq+qVWA09ucP0TGM+i1DNYJwg==","signatures":[{"sig":"MEUCIQCMs2ypXShHOBOVsf1Gniqyy5wIly/kaPiD2XHGUm/MCQIgZ2s9ISIRe5JVbCe/qR6urMEleTMtn3gZgLrp7XzSetU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":63389},"type":"commonjs","engines":{"node":">=18"},"gitHead":"b135918c78a63b0939537f32b27884dedd91eb91","scripts":{"test":"node npm/tests/cli-smoke.test.js","postinstall":"node npm/scripts/postinstall.js","test:global":"node npm/tests/global-install-smoke.test.js","release:check":"node npm/scripts/release-check.js","package:assets":"node npm/scripts/package-assets.js"},"_npmUser":{"name":"alemdarlabs","email":"admin@alemdarlabs.com"},"repository":{"url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Sage MCP server for Unreal Engine","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sage-mcp_0.1.4_1780617827661_0.5523702350667388","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@alemdarlabs/sage-mcp","version":"0.1.5","license":"UNLICENSED","_id":"@alemdarlabs/sage-mcp@0.1.5","maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"sage":"npm/bin/sage.js"},"cpu":["x64","arm64"],"dist":{"shasum":"c2127961fc933eb90aba1c42db7fff62c8794a1a","tarball":"https://registry.npmjs.org/@alemdarlabs/sage-mcp/-/sage-mcp-0.1.5.tgz","fileCount":19,"integrity":"sha512-O6Q1Vh2hbtNA+Adm/fxi9V2yR+SGqy9cUM04xf/20TTMk6KgNlWZBiqsJu96B200fuoOiLF707SwRCTlyBpmUA==","signatures":[{"sig":"MEUCIFYDN1NhWRk3+6ibT/OGXlwCXuu+op1L38EMQ55sRsq9AiEApo2BMg7hFygebmMAh0CHTctQFb+RWz4DwOLw4MC1Sv0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":82017},"type":"commonjs","engines":{"node":">=18"},"gitHead":"dda314b7e2c6aa8621d871bd2e62e639e29d72a8","scripts":{"test":"node npm/tests/cli-smoke.test.js","postinstall":"node npm/scripts/postinstall.js","test:global":"node npm/tests/global-install-smoke.test.js","release:check":"node npm/scripts/release-check.js","package:assets":"node npm/scripts/package-assets.js"},"_npmUser":{"name":"alemdarlabs","email":"admin@alemdarlabs.com"},"repository":{"url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Sage MCP server for Unreal Engine","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sage-mcp_0.1.5_1780664898894_0.7461225516051639","host":"s3://npm-registry-packages-npm-production"}},"0.1.6":{"name":"@alemdarlabs/sage-mcp","version":"0.1.6","license":"UNLICENSED","_id":"@alemdarlabs/sage-mcp@0.1.6","maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"os":["darwin","linux","win32"],"bin":{"sage":"npm/bin/sage.js"},"cpu":["x64","arm64"],"dist":{"shasum":"912b1893b2f352bff357b6dbb0e63ff5c5855a9a","tarball":"https://registry.npmjs.org/@alemdarlabs/sage-mcp/-/sage-mcp-0.1.6.tgz","fileCount":19,"integrity":"sha512-JVJWpXvIe8Ty/Lr1tqfzv+YxrDlfnkPWPaDI1daZH5k3uUy69SZ+MTLCIlWBVoaT3dMFjZf4+BTpIdm+fsXvtQ==","signatures":[{"sig":"MEUCIQDdTZJmxm7P03LPM4fgFvF5SqKmfmcTb2T/3kIwds0uNgIgWV5XCupWTn+hX4rLqLX3Sbe8NWmy2SvNE+YYGWLFXi4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":82017},"type":"commonjs","engines":{"node":">=18"},"gitHead":"9fc07f0b4d8d43fa8edfe6aa335dc4eb5dd90e72","scripts":{"test":"node npm/tests/cli-smoke.test.js","postinstall":"node npm/scripts/postinstall.js","test:global":"node npm/tests/global-install-smoke.test.js","release:check":"node npm/scripts/release-check.js","package:assets":"node npm/scripts/package-assets.js"},"_npmUser":{"name":"alemdarlabs","email":"admin@alemdarlabs.com"},"repository":{"url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git","type":"git"},"_npmVersion":"10.9.8","description":"Sage MCP server for Unreal Engine","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sage-mcp_0.1.6_1780667083496_0.4994498252895381","host":"s3://npm-registry-packages-npm-production"}},"0.1.13":{"name":"@alemdarlabs/sage-mcp","version":"0.1.13","description":"Sage MCP server for Unreal Engine","homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","license":"UNLICENSED","type":"commonjs","repository":{"type":"git","url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git"},"publishConfig":{"access":"public"},"bin":{"sage":"npm/bin/sage.js"},"scripts":{"package:assets":"node npm/scripts/package-assets.js","postinstall":"node npm/scripts/postinstall.js","release:check":"node npm/scripts/release-check.js","test":"node npm/tests/archive-contract.test.js && node npm/tests/cli-smoke.test.js","test:global":"node npm/tests/global-install-smoke.test.js"},"engines":{"node":">=18"},"os":["darwin","linux","win32"],"cpu":["x64","arm64"],"_id":"@alemdarlabs/sage-mcp@0.1.13","gitHead":"3d437aa9858aa0ce119e2f085875ec69cce8843b","bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-XtwqAmF+iKiRDt7CsJuVGPUHh7TzUnlJGmDfyE3zcbtXiFeDCXzPtWVdZBsgnev6xy6Fd9zxwd7KRKNAhDgKbQ==","shasum":"f01b36ee4843411b40a78fdce3265cdaded6edd3","tarball":"https://registry.npmjs.org/@alemdarlabs/sage-mcp/-/sage-mcp-0.1.13.tgz","fileCount":20,"unpackedSize":88848,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCr6Zd0TPAivhf5izGXAg6aW5OzaQXiV5R3mQDupTkI0wIgZZHwaOaASKBt3kJY3SI6EgHZB7oEsY5Fi0DPeyUFlFI="}]},"_npmUser":{"name":"alemdarlabs","email":"admin@alemdarlabs.com"},"directories":{},"maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sage-mcp_0.1.13_1780679292391_0.11612461324378587"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-04T20:08:55.320Z","modified":"2026-06-05T17:08:12.697Z","0.1.0":"2026-06-04T20:08:55.667Z","0.1.1":"2026-06-04T22:26:19.856Z","0.1.2":"2026-06-04T23:01:37.072Z","0.1.3":"2026-06-04T23:20:06.731Z","0.1.4":"2026-06-05T00:03:47.834Z","0.1.5":"2026-06-05T13:08:19.050Z","0.1.6":"2026-06-05T13:44:43.641Z","0.1.13":"2026-06-05T17:08:12.556Z"},"bugs":{"url":"https://github.com/alemdarlabs/sage-unreal-mcp/issues"},"license":"UNLICENSED","homepage":"https://github.com/alemdarlabs/sage-unreal-mcp","repository":{"type":"git","url":"git+https://github.com/alemdarlabs/sage-unreal-mcp.git"},"description":"Sage MCP server for Unreal Engine","maintainers":[{"name":"alemdarlabs","email":"admin@alemdarlabs.com"}],"readme":"# Sage Unreal MCP\n\n[![npm](https://img.shields.io/npm/v/@alemdarlabs/sage-mcp?label=npm)](https://www.npmjs.com/package/@alemdarlabs/sage-mcp)\n[![release](https://img.shields.io/github/v/release/alemdarlabs/sage-unreal-mcp?label=release)](https://github.com/alemdarlabs/sage-unreal-mcp/releases)\n[![workflow](https://github.com/alemdarlabs/sage-unreal-mcp/actions/workflows/release-assets.yml/badge.svg)](https://github.com/alemdarlabs/sage-unreal-mcp/actions/workflows/release-assets.yml)\n\n> Copyright (c) 2026 alemdarlabs. All rights reserved.\n>\n> Source-visible proprietary commercial software. Public repository visibility\n> and public npm distribution do not grant an open-source license.\n\nSage Unreal MCP is a native Model Context Protocol integration for Unreal\nEngine. It lets AI development clients inspect, reason about, and operate on an\nUnreal project through a C++ MCP server and an Unreal Editor plugin.\n\nSage is designed for production Unreal projects: multi-editor routing, native\nreflection, AssetRegistry-backed discovery, transactional editor operations,\nsource search, compile coordination, logs, crash forensics, and domain-specific\ntooling live behind one MCP surface.\n\n## Install\n\n```powershell\nnpm install -g @alemdarlabs/sage-mcp\nsage doctor\n```\n\nDuring install, Sage downloads the native server and attempts to register a\nglobal Codex MCP server named `sage` that launches `sage mcp`. If Codex is not\ninstalled yet, run this once after installing Codex:\n\n```powershell\nsage setup codex\n```\n\nAfter that, open Codex from any Unreal project directory. The `sage mcp`\nwrapper discovers the nearest `.uproject` from the current working directory and\npasses that project context to the native server.\n\nInstall or repair the Unreal plugin for the current project:\n\n```powershell\nsage bootstrap\n```\n\n`sage bootstrap` can also target a specific project:\n\n```powershell\nsage bootstrap \"<absolute-path-to-your-project.uproject>\"\n```\n\nLegacy project-local configuration remains available:\n\n```powershell\n$Project = \"<absolute-path-to-your-project.uproject>\"\n$UnrealRoot = \"<absolute-path-to-your-Unreal-Engine-install>\"\n\nsage init $Project --ue-root $UnrealRoot\n```\n\nValidate a project installation:\n\n```powershell\nsage doctor --json\n```\n\nPrint the packaged AI operating guide:\n\n```powershell\nsage guide codex\n```\n\n`sage bootstrap` installs `SageBridge` under `Plugins/SageBridge` and enables\nthe plugin in the `.uproject` without requiring `.mcp.json`. `sage init` does\nthe same and also writes project-local MCP config. If a previous\n`Plugins/SageBridge` directory exists, the installer backs it up before copying\nthe new package.\n\n## What Ships\n\nSage ships as two native components plus a thin npm CLI:\n\n| Component | Role |\n|---|---|\n| `sage-server` | C++23 MCP server with HTTP/SSE and stdio entry points, tool schema registration, job orchestration, release packaging, and multi-editor routing. |\n| `SageBridge` | Unreal Editor plugin that executes editor-safe operations through Unreal reflection, AssetRegistry, UTransactor, editor subsystems, and domain-specific tool modules. |\n| `sage` npm CLI | Installer and launcher that downloads native release assets, installs the Unreal plugin, writes MCP config, and starts the server for MCP clients. |\n\nThe npm package is lightweight. During `npm install`, the CLI downloads the\nnative `sage-server` binary into `~/.sage-mcp` and registers Codex when\navailable. During `sage bootstrap` or `sage init`, it resolves or downloads the\n`SageBridge` plugin package for the target Unreal project.\n\n## Release Target\n\n`v0.1.13` is the next release target for cross-platform server assets,\nzero-config Codex onboarding, project plugin version checks, and MCP-native Sage\nguidance tools. `v0.1.6` was the last Windows-only native asset release.\n\n```powershell\nnpm view @alemdarlabs/sage-mcp version dist.tarball\n```\n\nRelease assets:\n\n- `sage-server-0.1.13-win32-x64.zip`\n- `sage-server-0.1.13-linux-x64.tar.gz`\n- `sage-server-0.1.13-darwin-arm64.tar.gz`\n- `sage-server-0.1.13-darwin-x64.tar.gz`\n- `sagebridge-plugin-0.1.13-source.tar.gz`\n- `alemdarlabs-sage-mcp-0.1.13.tgz`\n- `checksums.txt`\n\nThe next release pipeline produces platform-specific `sage-server` assets for\nWindows x64, Linux x64, macOS arm64, and macOS x64, plus one platform-independent\nsource `SageBridge` plugin asset.\n\nThe plugin release asset is a download artifact only. Project installation\nalways uses the Unreal layout `Plugins/SageBridge`; version, platform, and\n`source` labels never become project folder names. GitHub-hosted runners do not\ninclude Unreal Engine, so binary `RunUAT BuildPlugin` packaging remains a\nself-hosted runner concern.\n\n## Architecture\n\n```text\nMCP client\n  |  stdio or HTTP/SSE\n  v\nsage-server\n  |  WebSocket bridge\n  v\nSageBridge Unreal Editor plugin\n  |  Unreal reflection, AssetRegistry, editor subsystems, transactions\n  v\nUnreal project\n```\n\nKey properties:\n\n- MCP clients talk to `sage-server`, not directly to Unreal.\n- `SageBridge` connects from the editor to the server over WebSocket.\n- Editor-scoped tools can target a specific editor session through `_editor`.\n- Long-running and mutating operations are modeled explicitly.\n- Project understanding is source-backed and live-editor-backed, not based on a\n  retired persistent graph runtime.\n\nADR-018 removed the KuzuDB graph layer. Current project understanding uses live\nUnreal inspection, reflection, AssetRegistry-backed discovery, source search,\nlogs, and specialized domain tools.\n\n## Tool Surface\n\nCurrent source audit, generated with `scripts/audit-tools.ps1 -Json` on\n2026-06-05:\n\n- `server_tool_count`: 1251\n- `plugin_handler_count`: 1191\n- `plugin_without_schema`: 0\n- `schema_stub_count`: 0\n- `plugin_not_implemented_count`: 0\n- `schema_without_plugin`: server-only `jobs.*` tools\n\nThe audit script is the source-level parity check for schemas, plugin handlers,\nstubs, and placeholder implementations.\n\n```powershell\n.\\scripts\\audit-tools.ps1 -Json\n```\n\n### AI Onboarding Tools\n\nSage is self-describing over MCP. Agents should not need to read this README\nbefore they can start safely.\n\n| Tool | Purpose |\n|---|---|\n| `sage.about` | Product identity, version, safety model, and first-call sequence. |\n| `sage.status` | Server, environment, project discovery, connected editors, and version alignment. |\n| `sage.doctor` | Actionable setup/version/editor checks with repair commands. |\n| `sage.project.discover` | Locate the Unreal project from `start_path`, `SAGE_PROJECT_ROOT`, or cwd. |\n| `sage.capabilities` | Group tool families and recommend first read-only tools. |\n| `sage.workflow.suggest` | Suggest a safe tool sequence for a natural-language task intent. |\n| `sage.help` / `sage.guide` | Compact operating guide for MCP clients. |\n\n## Safety Model\n\nSage is intended for real Unreal projects, not only throwaway samples.\n\n- Destructive tools require explicit confirmation.\n- Unreal editor mutation code must execute on the Game Thread.\n- Project plugin installation backs up an existing `Plugins/SageBridge`\n  directory before replacing it.\n- Production Blueprint migration or deletion workflows should take a\n  `bp.full_dump` first.\n- Multi-editor workflows should pass `_editor` explicitly when more than one\n  editor can be connected.\n- Build, deploy, server health, asset save, and runtime proof are separate\n  verification claims.\n\nThe CLI does not bypass source control. Check your Unreal project workspace\nbefore running install or mutation flows against production content.\n\n## CLI Reference\n\n```powershell\nsage --version\nsage doctor [Project.uproject] [--json]\nsage mcp [server args...]\nsage server [--http] [server args...]\nsage setup codex [options]\nsage guide [agent] [--json]\nsage bootstrap [Project.uproject] [options]\nsage init <Project.uproject> [options]\nsage update\nsage update <Project.uproject>\nsage update --plugin <Project.uproject>\n```\n\nCommon `init` options:\n\n```powershell\n--ue-root <path>         Add SAGE_UE_ROOT to generated MCP config\n--codex                  Register global Sage MCP in Codex CLI\n--claude                 Register the project in Claude Code\n--plugin-source <path>   Install from a local SageBridge package/source tree\n--mcp-config <path>      Write MCP config somewhere other than <project>/.mcp.json\n--no-mcp-config          Install plugin without writing MCP config\n```\n\n`sage update` without a project only repairs or downloads the machine-level\nnative server for the installed npm package. `sage update <Project.uproject>` is\nthe project-level update path: it verifies the server binary, refuses to copy\n`SageBridge` while that Unreal project is open, installs the matching plugin\npackage under `Plugins/SageBridge`, enables the plugin in the `.uproject`, and\nprints the installed plugin version. `sage doctor` reports the installed\n`SageBridge` version versus the current Sage CLI version and suggests\n`sage update \"<Project.uproject>\"` when they diverge. It also checks npm latest\nunless `--offline` or `SAGE_SKIP_NPM_LATEST=1` is set, and suggests\n`npm install -g @alemdarlabs/sage-mcp@latest` when the local CLI is stale.\n\nCommon `guide` options:\n\n```powershell\n--agent <name>           codex, claude, cursor, or generic\n--json                   Print {agent,path,content}\n```\n\nCommon `setup codex` options:\n\n```powershell\n--codex-name <name>      Codex MCP server name. Default: sage\n--codex-command <path>   Codex executable path. Default: codex\n--no-replace             Do not replace an existing non-Sage Codex MCP entry\n```\n\n## Configuration\n\n| Variable | Purpose |\n|---|---|\n| `SAGE_DATA_DIR` | Override the local Sage cache directory. Defaults to `~/.sage-mcp`. |\n| `SAGE_SERVER_PATH` | Use an explicit native server binary. |\n| `SAGE_PLUGIN_SOURCE` | Use an explicit unpacked SageBridge plugin source/package directory. |\n| `SAGE_BINARY_BASE_URL` | Override the GitHub Release base URL for native assets. |\n| `SAGE_PLUGIN_BASE_URL` | Override the GitHub Release base URL for plugin assets. |\n| `SAGE_BINARY_URL` | Override the exact server archive URL. |\n| `SAGE_PLUGIN_URL` | Override the exact plugin archive URL. |\n| `SAGE_SKIP_DOWNLOAD` | Skip postinstall native binary download for offline or development installs. |\n| `SAGE_POSTINSTALL_STRICT` | Set to `0` to make postinstall download failure non-fatal. |\n| `SAGE_SKIP_CODEX_SETUP` | Skip postinstall Codex MCP registration. |\n| `SAGE_CODEX_SETUP_STRICT` | Set to `1` to make postinstall Codex registration failure fatal. |\n| `SAGE_CODEX_COMMAND` | Override the Codex executable used by setup commands. |\n| `SAGE_SKIP_NPM_LATEST` | Skip `sage doctor` npm registry latest-version check. |\n| `SAGE_PROJECT_ROOT` | Unreal project root passed to the server or discovered by `sage mcp`. |\n| `SAGE_REPO_ROOT` | Workspace root passed to the server. Defaults to the discovered project root when available. |\n| `SAGE_UE_ROOT` | Unreal Engine install root used by build and editor workflows. |\n| `SAGE_LOG_LEVEL` | Runtime logging level. |\n| `SAGE_HTTP_HOST`, `SAGE_HTTP_PORT` | HTTP/SSE MCP bind address. Defaults to `127.0.0.1:7777`. |\n| `SAGE_WS_HOST`, `SAGE_WS_PORT` | Unreal plugin WebSocket bind address. Defaults to `127.0.0.1:7778`. |\n\n## Development\n\nRequirements:\n\n- Node.js 18 or newer\n- CMake 3.25 or newer\n- vcpkg\n- Ninja\n- Visual Studio toolchain on Windows\n- Unreal Engine for `RunUAT BuildPlugin` packaging\n\nBuild the server:\n\n```powershell\n$env:VCPKG_ROOT = \"$HOME\\vcpkg\"\ncmake --preset debug\ncmake --build --preset debug --target sage-server\n```\n\nRun native tests:\n\n```powershell\ncmake --build --preset debug --target sage-tests\nctest --preset debug --output-on-failure\n```\n\nPackage the Unreal plugin locally:\n\n```powershell\n$env:SAGE_UE_ROOT = \"<absolute-path-to-your-Unreal-Engine-install>\"\n.\\scripts\\build-plugin.ps1\n```\n\nRun npm packaging checks:\n\n```powershell\nnpm test\nnpm run test:global\nnpm run release:check\n```\n\nStart the server manually for local debugging:\n\n```powershell\n$env:SAGE_REPO_ROOT = (Get-Location).Path\n$env:SAGE_UE_ROOT = \"<absolute-path-to-your-Unreal-Engine-install>\"\n$env:SAGE_LOG_LEVEL = \"info\"\n.\\build\\debug\\bin\\sage-server.exe\n```\n\n## Release Process\n\nRelease tags are `v<package.json version>`.\n\nOn a tag push, GitHub Actions:\n\n1. Builds `sage-server` on Windows x64, Linux x64, macOS arm64, and macOS x64.\n2. Builds and runs native tests on each server runner.\n3. Runs npm smoke and release checks on each server runner.\n4. Packages one platform-specific server asset per runner.\n5. Packages one platform-independent source `SageBridge` plugin asset.\n6. Merges artifacts, writes `checksums.txt`, and uploads GitHub Release assets.\n7. Publishes `@alemdarlabs/sage-mcp` to npm.\n\n`NPM_TOKEN` must be configured as a GitHub repository secret. For accounts with\n2FA, the token must support CI publish workflows.\n\n## Repository Layout\n\n```text\nsage-unreal-mcp/\n|-- .agents/                 # Codex skill definitions\n|-- .github/                 # CI and release workflows\n|-- docs/\n|   |-- adr/                 # Architectural Decision Records\n|   |-- architecture/        # Active architecture docs\n|   |-- engineering/         # API, build, project structure, pipelines\n|   |-- release/             # npm and binary distribution notes\n|   |-- research/            # Tool parity and product research\n|   `-- archive/             # Historical notes and retired designs\n|-- npm/                     # npm CLI, installer, postinstall, smoke tests\n|-- plugin/                  # Unreal SageBridge plugin source\n|-- scripts/                 # Build, package, audit, smoke helpers\n|-- server/                  # C++23 MCP server\n|-- tests/                   # Catch2 unit and integration tests\n|-- AGENTS.md                # Canonical agent and development guide\n|-- BUILD.md\n|-- CMakeLists.txt\n|-- CMakePresets.json\n|-- package.json\n`-- vcpkg.json\n```\n\nRuntime logs, smoke output, debugger dumps, release artifacts, and temporary\nanalysis files should not live in the repository root. Use ignored artifact,\nlog, temp, or build directories.\n\n## Documentation\n\n- [Agent Guide](AGENTS.md)\n- [Architecture](docs/architecture/architecture.md)\n- [Tech Stack](docs/engineering/tech-stack.md)\n- [API Spec](docs/engineering/api-spec.md)\n- [Project Structure](docs/engineering/project-structure.md)\n- [Compile Coordination](docs/engineering/compile-coordination.md)\n- [Blueprint to C++ Pipeline](docs/engineering/bp-cpp-conversion-pipeline.md)\n- [Transactions](docs/engineering/transactions.md)\n- [ADRs](docs/adr/)\n- [npm Distribution Plan](docs/release/npm-distribution-plan.md)\n- [Reference Tool Parity Research](docs/research/tool-parity/)\n\nHistorical notes and retired designs are kept under `docs/archive/`.\n\n## License\n\nThis repository is source-visible proprietary software. There is no open-source\nlicense grant in this repository. Do not treat public repository access, npm\npackage availability, or GitHub Release availability as permission to copy,\nfork, resell, sublicense, or redistribute the source code outside alemdarlabs\nterms.\n","readmeFilename":"README.md"}