From 12b0930c0f8a8b598f692ded795b0ee282956262 Mon Sep 17 00:00:00 2001 From: basielienis Date: Sat, 8 Aug 2026 17:06:32 +0300 Subject: [PATCH] feat: initial Spaghetti UE5 Agent Plugin (Agent Plugins 1.0.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agent Plugins 1.0.0 distribution package for Spaghetti Unreal AI Workbench. Structure: - plugin.json: manifest (spaghetti-ue5 v0.1.0, Tinirau Ltd, MIT) - mcp.json: streamable-http → https://mcp.spaghetti.gg (OAuth, no secrets) - skills/ue5-unreal/SKILL.md: AI-facing tool routing for Crash Investigator, Asset Janitor, Smart Librarian, Tool-Maker + safety defaults - README.md: install (npx plugins add), auth (OAuth browser flow), .spaghetti context note - LICENSE: MIT OAuth flow: client connects → 401 + WWW-Authenticate → RFC 9728 metadata → GoTrue SSO → token. All server-side; no client-side secrets. .spaghetti context file: {team_id, project_id} at the UE project root. The mcp_server field is not included — mcp.json owns the URL. --- .gitignore | 2 + LICENSE | 21 ++++++++ README.md | 65 ++++++++++++++++++++++++ mcp.json | 9 ++++ plugin.json | 14 ++++++ skills/ue5-unreal/SKILL.md | 100 +++++++++++++++++++++++++++++++++++++ 6 files changed, 211 insertions(+) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 README.md create mode 100644 mcp.json create mode 100644 plugin.json create mode 100644 skills/ue5-unreal/SKILL.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9fa88ac --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.DS_Store +*.log diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2382f6a --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Tinirau Ltd + +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. diff --git a/README.md b/README.md new file mode 100644 index 0000000..12c97e7 --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# Spaghetti UE5 Agent Plugin + +Agent Plugins 1.0.0 distribution package for [Spaghetti Unreal AI Workbench](https://spaghetti.gg) — AI-powered tools for Unreal Engine 5.8 developers. + +## What this gives you + +Connects your AI coding assistant (Claude Code, Cursor, Codex, etc.) to the Spaghetti MCP server, providing: + +- **Crash Investigator** — paste a UE5 crash log, get a root-cause diagnosis + fix +- **Asset Janitor** — audit naming conventions, find unused assets, check LODs +- **Smart Librarian** — semantic search over UE5 engine docs + your team's knowledge base +- **Tool-Maker** — generate safe Python scripts for UE5 editor automation + +## Install + +```bash +# Universal installer (detects Claude Code, Cursor, Codex, VS Code, etc.) +npx plugins add Tinirau/ue5-agent-plugin + +# Dry-run to inspect before installing +npx plugins discover Tinirau/ue5-agent-plugin + +# Or, in Claude Code: +/plugin marketplace add Tinirau/ue5-agent-plugin +``` + +## Authentication + +On first connect, your client opens a browser to sign in at [spaghetti.gg](https://spaghetti.gg) via OAuth (GoTrue). No API key or headers to configure — the OAuth flow is handled entirely by your client. + +## Project context + +Your UE5 project needs a `.spaghetti` file at its root: + +```json +{ + "team_id": "tm_your_team", + "project_id": "prj_your_project" +} +``` + +Get these from your [spaghetti.gg dashboard](https://spaghetti.gg/dashboard). The file is safe to commit to Git/Perforce (no secrets). If it's missing, the first tool call guides you through creating it. + +## Structure + +``` +ue5-agent-plugin/ +├── plugin.json # Agent Plugins 1.0.0 manifest +├── mcp.json # streamable-http → mcp.spaghetti.gg (OAuth, no embedded secrets) +├── skills/ +│ └── ue5-unreal/ +│ └── SKILL.md # AI-facing instructions: when/how to call each tool +├── LICENSE +└── README.md +``` + +## Requirements + +- An AI client that supports [Agent Plugins 1.0.0](https://agent-plugins.org) (Claude Code, Cursor, OpenAI Codex, etc.) +- A Spaghetti account ([sign up](https://spaghetti.gg/signup)) +- UE 5.8+ (for built-in MCP tool integration; the Spaghetti tools work with 5.6+ for non-MCP features) + +## License + +MIT © Tinirau Ltd diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..406e954 --- /dev/null +++ b/mcp.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "spaghetti": { + "type": "streamable-http", + "url": "https://mcp.spaghetti.gg" + } + } +} diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000..95c3ae2 --- /dev/null +++ b/plugin.json @@ -0,0 +1,14 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "spaghetti-ue5", + "version": "0.1.0", + "description": "Unreal Engine 5 agent tools — crash analysis, asset auditing, knowledge base, code generation. Powered by Spaghetti Unreal AI Workbench.", + "author": { + "name": "Tinirau Ltd", + "url": "https://spaghetti.gg" + }, + "homepage": "https://spaghetti.gg", + "repository": "https://git.tinirau.com/Tinirau/ue5-agent-plugin", + "license": "MIT", + "keywords": ["unreal", "ue5", "spaghetti", "mcp", "game-development", "ai"] +} diff --git a/skills/ue5-unreal/SKILL.md b/skills/ue5-unreal/SKILL.md new file mode 100644 index 0000000..817de16 --- /dev/null +++ b/skills/ue5-unreal/SKILL.md @@ -0,0 +1,100 @@ +--- +name: ue5-unreal +description: > + Unreal Engine 5 development assistant — crash analysis, asset auditing, + knowledge-base search, and Python script generation via Spaghetti Unreal AI + Workbench. Call these tools when the user is working in a UE5 project and + needs expert help with crashes, asset cleanup, engine docs, or editor + automation. +--- + +# UE5 Unreal AI Workbench Tools + +This skill provides access to Spaghetti's Unreal AI Workbench MCP tools. +These tools run on a remote server (`mcp.spaghetti.gg`) and require +authentication via OAuth (your client handles this automatically on first +connect — a browser window opens for sign-in at spaghetti.gg). + +## Prerequisites + +Your UE5 project must have a `.spaghetti` file at its root containing +`team_id` and `project_id`. If no `.spaghetti` exists, the first tool call +returns an Agentic Directive instructing you to create one. Follow it. + +## Available tools (Phase 1 — MVP) + +### Crash Investigator (`spaghetti/analyze_crash`) + +**When to call:** The user reports a UE5 crash, paste an output log, or +mentions a crash dump / minidump. + +**What it does:** Parses the UE5 Output Log and crash dumps, identifies +root-cause nodes or C++ pointers, and returns a precise fix with context from +the proprietary UE5 bug knowledge base. + +**Input:** Crash log text (paste the Output Log contents or the relevant +section). + +**Safety:** Read-only analysis. Returns a diagnosis + suggested fix; does +not modify project files. + +### Asset Janitor (`spaghetti/audit_assets`) + +**When to call:** The user asks about asset cleanup, naming conventions, unused +assets, missing LODs, or compliance reports. + +**What it does:** Finds textures without LODs, detects naming-convention +violations (`T_`, `BP_`, etc.), identifies unused/0-reference assets, and +generates compliance reports. + +**Input:** Optionally specify which checks to run (naming, LODs, unused). + +**Safety:** Audit is read-only. If the user wants to apply fixes, use +Tool-Maker to generate a dry-run Python script first. + +### Smart Librarian (`spaghetti/search_kb`) + +**When to call:** The user asks about UE5 engine architecture, best practices, +or how specific systems work. Also for snippet search (verified node setups, +Blueprint patterns). + +**What it does:** Semantic search over two knowledge bases: +- **Team KB:** your project's private RAG index (studio docs, past bug + resolutions, conventions). +- **UE5 Engine Graph:** GraphRAG over the public UE 5.8 source for multi-hop + reasoning about engine architecture. + +**Input:** Natural-language query about UE5 or your project's knowledge base. + +### Tool-Maker (`spaghetti/make_tool`) + +**When to call:** The user wants to automate a UE5 editor task (batch-rename +assets, apply materials, configure project settings, etc.). + +**What it does:** Generates a safe, production-quality Python script using +`unreal.EditorAssetLibrary` API. The script runs via the UE 5.8 Python remote +execution bridge. + +**Safety — three-layer model:** +1. **API allowlist:** only approved `unreal.EditorAssetLibrary` functions. +2. **Dry run:** scripts default to simulation mode (log what would happen, + don't execute destructive ops). +3. **Human approval:** before any destructive script runs, the user sees an + Approve/Reject dialog. + +**Always show the generated script to the user before executing.** If the +script modifies assets, wrap in `unreal.ScopedTransaction` for undo support. + +## Safety defaults + +- **Never auto-delete assets** without explicit user confirmation. +- **Prefer dry-run mode** for any script that modifies the project. +- **Use ScopedTransaction** for reversible operations (enables Ctrl+Z). +- **Read the Output Log** for errors after any automated editor operation. + +## Context + +The `.spaghetti` file at the project root identifies which team and project +this UE5 project belongs to. All tool calls are billed to the team's Spaghetti +wallet. If you see a `402 Payment Required`, direct the user to +`spaghetti.gg/billing` to top up.