Hugging Face's logo

Spaces:
barlowski
/
KarianaUMCP
Sleeping

App Files Community
KarianaUMCP / UMCP_DOCUMENTATION_INDEX.md
barlowski's picture
barlowski
Upload folder using huggingface_hub
5ccfb25 verified
preview code
|
raw
history blame contribute delete
10.9 kB

A newer version of the Gradio SDK is available: 6.8.0

Upgrade

UMCP Tool Analysis - Documentation Index

Analysis Date: 2025-11-30 14:04:43 Server: KarianaUMCP v1.0.0 Status: All systems operational (100% test pass rate)

Quick Start

  1. Read this first: UMCP_ANALYSIS_SUMMARY.md - Complete system overview
  2. For daily use: UMCP_QUICK_REFERENCE.md - Command cheat sheet
  3. For testing: UMCP_TEST_PLAN.md - Comprehensive test procedures

Documentation Files

1. UMCP_ANALYSIS_SUMMARY.md (14 KB)

Purpose: Comprehensive analysis report Contents:

  • Executive summary
  • Complete tool inventory (29 tools)
  • Skill system documentation (6 skills)
  • Recommended test scenarios
  • Architecture analysis
  • Security considerations
  • Performance metrics
  • Integration guide

Use when: You need complete system documentation or are onboarding new users.

2. UMCP_QUICK_REFERENCE.md (7.5 KB)

Purpose: Quick command reference card Contents:

  • Essential commands with examples
  • Actor operations cheat sheet
  • Python execution examples
  • Common workflows
  • Error handling guide
  • Parameter types reference

Use when: You're actively working with UMCP and need quick syntax lookup.

3. UMCP_TEST_PLAN.md (11 KB)

Purpose: Structured testing protocol for Claude Desktop Contents:

  • 9 test suites (28 core tests)
  • Step-by-step test procedures
  • Expected results for each test
  • Scorecard for tracking results
  • Issue reporting template
  • Performance metrics

Use when: Testing UMCP integration with Claude Desktop or validating system health.

4. umcp_tool_monitor.py (21 KB)

Purpose: Python monitoring and analysis tool Contents:

  • Connection testing utilities
  • Tool discovery functions
  • Automated test runner
  • Report generator
  • Real-time monitoring (future enhancement)

Usage:

# Generate full analysis report
python3 umcp_tool_monitor.py --report

# Test basic tools
python3 umcp_tool_monitor.py --test

# Quick server status
python3 umcp_tool_monitor.py

# Monitor activity (basic)
python3 umcp_tool_monitor.py --monitor --duration 120

Use when: You need programmatic access to UMCP or want to automate testing.

5. umcp_tools_detailed.txt (4.8 KB)

Purpose: Detailed parameter documentation Contents:

  • All 29 tools organized by category
  • Parameter specifications
  • Required vs optional parameters
  • Parameter types and defaults

Use when: You need detailed parameter information for a specific tool.

6. umcp_analysis_20251130_140443.txt (7.6 KB)

Purpose: Raw analysis report output Contents:

  • Server information
  • Instance discovery results
  • Tool categorization
  • Test results
  • Key observations

Use when: You need the original analysis data or want to compare with future reports.

System Overview

Connection Details

  • Local Socket: localhost:9877
  • ngrok Tunnel: 7.tcp.eu.ngrok.io:14199
  • Authentication: PIN-based (Current PIN: 4336)
  • Protocol: JSON over TCP, newline-delimited

Tool Inventory

29 Total Tools:

  • Actors: 8 tools (27.6%) - spawn, delete, move, rotate, scale, list, query
  • Blueprints: 6 tools (20.7%) - create, modify, compile, auto-wire
  • Assets: 5 tools (17.2%) - list, import, create, query, save
  • Editor: 3 tools (10.3%) - PIE control, camera
  • Skills: 2 tools (6.9%) - list, execute
  • Python: 1 tool (3.4%) - execute code
  • Screenshot: 1 tool (3.4%) - capture viewport
  • System: 3 tools (10.3%) - ping, list functions, utilities

Skill System

6 Available Skills:

  1. screenshot - High-quality viewport rendering
  2. blueprint-helper - Blueprint creation and management
  3. spawn-actor - Advanced actor spawning
  4. level-organizer - World Outliner organization
  5. organize_level - Legacy level organization
  6. create_lighting_setup - Three-point lighting

Test Results

Core Functionality Tests: 5/5 passed (100%)

  • ✓ ping
  • ✓ list_actors
  • ✓ get_current_level
  • ✓ list_assets
  • ✓ list_skills

Common Use Cases

Use Case 1: Scene Creation from Claude Desktop

Documentation: UMCP_QUICK_REFERENCE.md → Workflow 1 Steps:

  1. Spawn actors with positions
  2. Apply transformations
  3. Organize with level-organizer skill
  4. Capture screenshot for validation

Use Case 2: Asset Discovery and Management

Documentation: UMCP_ANALYSIS_SUMMARY.md → Asset Management Steps:

  1. List assets in /Game folder
  2. Query specific asset info
  3. Create materials or import new assets
  4. Save changes

Use Case 3: Python-Driven Automation

Documentation: UMCP_QUICK_REFERENCE.md → Python Execution Steps:

  1. Write Python code using Unreal API
  2. Execute via execute_python command
  3. Batch operations for efficiency
  4. Error handling and logging

Use Case 4: Blueprint Automation

Documentation: UMCP_ANALYSIS_SUMMARY.md → Blueprint Operations Steps:

  1. Create blueprint via tool
  2. Add components
  3. Use auto_wire_blueprint for connections
  4. Compile and test

Architecture Highlights

Multi-Instance Support

  • Automatic port allocation
  • Instance discovery mechanism
  • Token-based authentication per instance
  • Current instance: kariana-11025-1764507256524-29acaf30

Progressive Disclosure

  • Core tools for atomic operations
  • Skills for complex workflows
  • Lazy loading of advanced features
  • Modular architecture (46 handlers, 29 exposed)

Thread Safety

  • Thread-safe commands: ping, list_*, get_server_info
  • Main-thread commands: All Unreal API calls
  • Queue-based execution for thread safety
  • 15-second timeout for main thread operations

Integration Patterns

Pattern 1: Direct Socket Communication 

import socket, json

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(('localhost', 9877))
request = {'type': 'spawn_actor', 'pin': '4336', 'actor_class': 'Cube', 'name': 'Test'}
sock.sendall(json.dumps(request).encode() + b'\n')
response = sock.recv(4096)

Pattern 2: Claude Desktop MCP 

User: "Create 10 cubes in a circle pattern"

Claude uses:
1. execute_python with math for circle calculations
2. Multiple spawn_actor calls
3. set_actor_location for positioning
4. execute_skill('level-organizer') for cleanup

Pattern 3: Python-Driven Batch Operations 

code = """
import unreal
for i in range(10):
    location = [i*100, 0, 0]
    actor = unreal.EditorLevelLibrary.spawn_actor_from_class(
        unreal.Cube.static_class(), location
    )
"""

umcp_command('execute_python', code=code)

Troubleshooting Guide

Issue: Connection Refused

Symptoms: Cannot connect to localhost:9877 Solutions:

  1. Verify Unreal Engine is running
  2. Check KarianaUMCP plugin is enabled
  3. Look for "KarianaUMCP: Listening on port 9877" in UE log
  4. Restart socket server via Python: unreal.PythonScriptPlugin.execute_script(...)

Issue: Authentication Failed

Symptoms: "Authentication required" error Solutions:

  1. Include PIN in request: {"pin": "4336", ...}
  2. Get current PIN: {"type": "get_pin"}
  3. Check Unreal log for PIN display

Issue: Actor Not Found

Symptoms: "Actor not found" or similar Solutions:

  1. List actors first: {"type": "list_actors"}
  2. Use exact name (case-sensitive)
  3. Verify actor exists in World Outliner
  4. Use full path if needed: /Game/Level.Level:PersistentLevel.ActorName

Issue: Command Timeout

Symptoms: No response after 15 seconds Solutions:

  1. Check Unreal is not frozen
  2. Simplify operation (break into smaller commands)
  3. Use Python execution for long operations
  4. Check Unreal log for Python errors

Performance Considerations

Response Times

  • Fast (<100ms): ping, list_functions, list_actors
  • Medium (100-500ms): spawn_actor, set_actor_*, list_assets
  • Slow (500ms+): execute_python (depends on code), skills, screenshots

Best Practices

  1. Batch operations via Python instead of multiple tool calls
  2. Use skills for workflows rather than manual orchestration
  3. Cache actor lists instead of querying repeatedly
  4. Test with ping before complex operations

Limits

  • Max timeout: 15 seconds for main thread operations
  • Concurrent requests: Single-threaded, queued execution
  • Screenshot size: Default 800x600 (configurable)

Security Notes

Current Configuration

  • Authentication: PIN-based (4336)
  • Public exposure: ngrok tunnel active
  • Token system: Available but not required

Recommendations

  1. Rotate PIN when using ngrok
  2. Enable token auth for production
  3. Restrict network access in sensitive environments
  4. Audit Python execution requests
  5. Monitor for unusual activity

Version History

v1.0.0 (2025-11-30)

  • Initial analysis and documentation
  • 29 tools discovered and documented
  • 6 skills cataloged
  • 100% test pass rate on core functionality
  • Monitor tool created
  • Complete documentation suite generated

Future Enhancements

Short-Term

  • Document missing tool parameters (create_blueprint, import_asset, etc.)
  • Add level save/load tools
  • Console command tool
  • Real-time log streaming

Medium-Term

  • Batch operation tools
  • Asset validation tools
  • Blueprint debugging tools
  • Performance profiling

Long-Term

  • Real-time monitoring dashboard
  • Tool usage analytics
  • Automated testing CI/CD
  • Multi-project support

Contact and Support

Documentation Issues

Report missing or incorrect information in these docs.

Tool Issues

Check Unreal Engine output log for errors.

Enhancement Requests

Document desired new tools or improvements to existing ones.

Appendices

Appendix A: File Sizes

  • UMCP_ANALYSIS_SUMMARY.md: 14 KB
  • UMCP_QUICK_REFERENCE.md: 7.5 KB
  • UMCP_TEST_PLAN.md: 11 KB
  • umcp_tool_monitor.py: 21 KB
  • umcp_tools_detailed.txt: 4.8 KB
  • umcp_analysis_20251130_140443.txt: 7.6 KB

Total Documentation: ~66 KB

Appendix B: Tool Categories Distribution 

Actors        ████████ 27.6%
Blueprints    ██████ 20.7%
Assets        █████ 17.2%
Editor        ███ 10.3%
System        ██ 6.9%
Skills        ██ 6.9%
Python        █ 3.4%
Screenshot    █ 3.4%
Other         █ 3.4%

Appendix C: Test Coverage

  • Basic connectivity: 2 tests
  • Actor operations: 6 tests
  • Scene discovery: 3 tests
  • Python execution: 3 tests
  • Skill system: 3 tests
  • Editor control: 2 tests
  • Complex workflows: 4 tests
  • Error handling: 3 tests
  • Performance (optional): 2 tests

Total: 28 tests

Documentation Version: 1.0.0 Last Updated: 2025-11-30 14:08:00 Maintainer: MCP Tool Analyzer Agent Status: Complete and Validated