K O S H (कौश)

Minimalist Developer-First Creative Model Context Protocol (MCP) Workstation
Real-Time Parametric 3D CAD • Digital Sculpting • Procedural Animation • Headless Blender 5.2 LTS

[!NOTE]
Live Demo Walkthrough: Demonstrates real-time 3D model synthesis, interactive viewport manipulation, DCC inspector synchronization, and headless Blender MCP integration. High-resolution 60fps recording is also available at assets/videos/demo.mp4.

Overview

Kosh (कौश — treasury / vessel of creation) is a high-performance, minimalist 3D workstation and Model Context Protocol (MCP) server hub. It bridges modern AI coding assistants with native desktop Blender 5.2 LTS in headless execution mode, allowing developers and designers to synthesize, manipulate, animate, and color 3D assets on the fly via JSON-RPC 2.0.

Built with a titanium-slate CAD workstation aesthetic, Kosh couples a Spring Boot 3.3 / Java 21 MCP server with an interactive Next.js 15 / Three.js digital content creation (DCC) studio.

Architecture

 ┌─────────────────────────────────────────────────────────────┐
 │                LLM / AI Agent / MCP Client                  │
 │      (Claude Desktop / Antigravity / Cursor / Gemini)       │
 └──────────────────────────────┬──────────────────────────────┘
                                │ JSON-RPC 2.0 (POST /mcp)
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │            Spring Boot 3.3 MCP Server (:8080)               │
 │  ├─ McpController (/mcp)        ├─ ShareController (/api)   │
 │  ├─ McpToolRegistry (82 Tools)  ├─ AssetController          │
 │  ├─ McpResourceRegistry (20)    ├─ McpPromptRegistry (13)   │
 │  └─ GoogleGeminiClient (BYOK)   └─ BlenderExecutionService  │
 └──────────────────────────────┬──────────────────────────────┘
                                │ Subprocess Execution
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │           Headless Blender Engine 5.2.1 LTS                 │
 │  ├─ bpy / bmesh                 ├─ Dynamic Sculpting        │
 │  ├─ Geometry Nodes              ├─ Shader Graph / Matcaps   │
 │  ├─ Rigid Body / Particle Sim   └─ GLTF/GLB/STL Exporters   │
 └──────────────────────────────┬──────────────────────────────┘
                                │ Compiled 3D Buffers (.glb)
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │            Next.js 15 Terminal Studio (:3000)               │
 │  ├─ 3D Viewport Navigation Gizmo (6-Axis Depth-Projected)   │
 │  ├─ All-in-One Universal Transform Handles (Move/Rot/Scale) │
 │  ├─ Dope Sheet Animation Timeline with Keyframe Diamonds    │
 │  ├─ Multi-Palette CAD Theme Engine (Titanium/Blender/Nordic)│
 │  ├─ Standalone 1-File HTML Exporter & Share Route (/share)  │
 │  └─ Hardware-Accelerated Canvas Protractor & Marquee Engine │
 └─────────────────────────────────────────────────────────────┘

Expanded Creative MCP Tools Suite

Kosh exposes a comprehensive suite of 85 native creative CAD, DCC, repair, and surgical manipulation tools over JSON-RPC 2.0 (POST /mcp and GET /mcp/sse), every single one declaring explicit boolean behavioral hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) for full M8ven Trust Index Grade A compliance:

Precision 3D CAD & Engineering

Instant Assembly & Kitbashing (Zero LLM Latency)

Photorealistic Rendering & Studio Lighting

Digital Sculpting, Animation & Multi-Domain

Arrays, Typography & Print Validation

Online Models & Verified Asset Ingestion

Parametric DCC & Extended Procedural Pipeline

Surgical CAD Modification Suite

Advanced Geometric Repair, Assembly & Kinematics

Enterprise MCP Resources (26 Direct In-Memory Schemas)

Kosh pre-serializes domain knowledge into JVM memory at startup for sub-2ms resources/read resolution, eliminating LLM dimension hallucinations:

Precision Engineering MCP Prompts (19 Standardized Blueprints)

Connected LLM clients (Claude Desktop, Cursor, Gemini) can query prompts/list and prompts/get to pull hardened step-by-step CAD plans with zero syntax hallucinations:

Modular Puzzle-Piece Assembly Engine & Saved Models Library

Kosh introduces a physical interlocking assembly subsystem where CAD components act like modular puzzle pieces with calibrated socket vectors, enabling AI agents and connected clients to stitch components together to satisfy complex user queries with zero manual CAD modeling.

1. Interlocking Puzzle Pieces (kosh://library/puzzle-pieces)

The resource exposes 12 parametric CAD puzzle pieces adhering to the Kosh Modular Interlocking Standard (KMIS-2026), each specifying exact envelope dimensions, socket connection points, normal vectors, and 0.2mm nominal slide-fit tolerances:

1. dovetail_male_plate: 30x30x6mm planar plate with male dovetail tongue on +X and female groove on -X (15-degree wedge angle).
2. dovetail_female_plate: 30x30x6mm planar plate with dual female dovetail grooves for bidirectional interlocking.
3. corner_gusset_90: 25x25x20mm structural right-angle gusset with dual M3 counterbored holes and internal stiffening rib.
4. t_slot_rail_2020: 20x20x100mm metric extrusion rail featuring standard 6mm slot profiles along 4 faces and central M5 tap core.
5. bearing_block_608: 36x36x12mm pillow block housing with press-fit pocket for 608 ball bearings (22mm outer diameter, 8mm bore).
6. nema17_motor_mount: 42.3x42.3x8mm stepper motor faceplate with 22.5mm pilot boss clearance and 31mm square PCD M3 bolt pattern.
7. cantilever_strut: 14x14x80mm lightweight I-beam linkage strut with clevis pin pivot ends.
8. ball_socket_joint: 20x20x28mm spherical ball-and-cup joint delivering +/- 35-degree conical articulation.
9. hex_hub_6way: 32x32x15mm isogrid anchor node radiating 6 structural sockets at 60-degree increments for space frames.
10. snap_fit_enclosure_base: 80x50x20mm perimeter snap-bead enclosure base with 4 internal PCB standoffs.
11. snap_fit_enclosure_lid: 80x50x6mm mating lid with flexible cantilever hooks (0.25mm retention engagement).
12. servo_horn_linkage: 40x12x5mm actuator arm featuring a standard 25T spline hub and M2 pushrod clevis hole.

2. Turnkey Composite Assembly Recipes

When an AI assistant receives natural language user requests, it matches them directly to pre-solved puzzle piece recipes executed deterministically via cad_assemble_puzzle_pieces:

• interlocking_dovetail_plate ("puzzle floor tile", "modular interlocking plates"): 4-tile planar lattice joined via 0.2mm slide dovetails with alternating dark titanium and brushed brass finishes.
• robotic_articulated_arm ("robotic arm", "servo manipulator", "pick and place robot"): Multi-jointed arm mating a NEMA 17 motor mount, 608 bearing pivot, twin linkage struts, and servo clevis horn.
• modular_cube_chassis ("cube frame", "extrusion chassis", "3D printer cage"): Rigid 3D cubic enclosure assembled from 12 2020 extrusion rails joined by 8 90-degree corner gussets.
• geodesic_hex_truss ("hex truss", "space frame", "honeycomb lattice"): Isogrid structural node radiating 60-degree interlocking struts into an outer tension perimeter.
• bearing_transmission_carrier ("transmission plate", "gearbox carrier", "motor bearing mount"): Mechanical powertrain sub-assembly mating a NEMA 17 faceplate to twin 608 pillow blocks across dual 2020 rails with a precision 8mm ground shaft.

3. Pre-Engineered Saved Complete Assemblies (kosh://library/saved-models)

For instant turn-key prototyping, Kosh pre-bakes complete multi-part CAD assemblies accessible directly through the resource registry:

1. drone_quadcopter_pro: Enterprise Pro Quadcopter Airframe (350x350x85mm) featuring carbon fiber arms, brushless motor mounts, avionics canopy, and landing skids.
2. planetary_gearbox_stage: Epicyclic Planetary 4:1 Gearbox (80x80x45mm) with 48T outer ring gear, 16T central sun gear, 3 planet gears on carrier plate, and 8mm input shaft.
3. biomedical_microscope_body: Laboratory Optical Compound Microscope (180x220x360mm) with cast iron arm, revolving quad objective turret, mechanical XY stage, and focus dials.
4. modular_electronics_housing: IP54 DIN-Rail Instrument Housing (120x80x40mm) with O-ring gasket groove, transparent polycarbonate lid, PG7 cable gland knockouts, and 35mm DIN-rail spring clip.
5. cosmic_astronaut_scene: Cinematic Apollo Astronaut Diorama (250x250x300mm) situated atop a cratered asteroid pedestal with dust rings and orbiting crystals.

Core Studio Features

1. Modern 3D Viewport Navigation Gizmo

• 6-Axis Real-Time Depth Sorting: Projects cardinal axes (+X, -X, +Y, -Y, +Z, -Z) via camera.matrixWorldInverse. Back axes render with subtle dashed stems and muted dots; front axes render with solid stems and sharp circular pill badges.
• Smooth Easing Snap: Clicking any axis animates the viewport camera into orthogonal alignment over 300ms using ease-out cubic interpolation (1 - (1 - t)³).
• Interactive Drag Orbit: Dragging anywhere on the gizmo background disc smoothly orbits the scene in spherical coordinates.
• Center Isometric Hub: Center dot resets the camera view smoothly to Isometric (iso).
• HUD Mode Pill: Displays current view (e.g. FRONT ORTHO, USER PERSPECTIVE) with 1-click Perspective / Orthographic projection toggle.

2. Universal Transform Gizmo

• Unified Axis Progression:
  • (0, 0, 0): Chamfered Zinc-white cube for uniform 3-axis scaling (0.18).
  • 0.28: Planar drag squares (XY Amber, XZ Cyan, YZ Purple) for smooth 2D sliding.
  • 0.65: Scale cubes positioned cleanly along shafts inside the rotation ring envelope.
  • 0.85: Rotation arc torus rings (0.016 tube radius, 64 segments).
  • 1.15: Translation arrow cones (0.075 radius).
• Dedicated Modes: Seamlessly switch between All (Q), Select (V), Move (W), Rotate (E), and Scale (R).
• Z-Fighting Prevention: Visual handles render with renderOrder = 99999 and depthTest = false.

3. Dope Sheet Animation Timeline

• Keyframe Diamond Markers (◆): Visual indicators at transformation keyframes. Click diamonds to snap the scrubber head; drag diamonds to retime the sequence.
• Parametric Exploded View Slider: 0% to 100% real-time disassembly slider using bounding box radial displacement vectors.
• Playback Controls: Play/Pause, Rewind, Looping, Frame counter, and Timecode display (00:00:00).

4. 2-Way Blender Script Ingestion & Standalone HTML Export

• Paste bpy Script: Paste raw Python scripts copied from Blender's Scripting workspace. The backend executes them headlessly and streams the resulting .glb directly into the viewport.
• Standalone 1-File HTML Exporter: Exports an autonomous, self-contained single .html file embedding the model buffer (Base64) and Three.js from CDN with OrbitControls, directional lighting, and turntable rotation—zero server required.
• Community Model Sharing & 1-Click Forking: Share creations via /share/[id] with 3D cards, metadata, and an instant [ Fork in Kosh Studio ] workflow.

Prerequisites

Ensure the following tools are installed and available in $PATH:

Quickstart

Automated 1-Click Boot

Run the bootloader script, which verifies prerequisites, compiles the backend, and boots both services:

chmod +x run.sh
./run.sh

• Web Studio: http://localhost:3000
• MCP Server: http://localhost:8080
• Health Check: curl http://localhost:8080/api/health

Manual Run

1. Backend MCP Server (Port 8080)

cd backend
mvn clean spring-boot:run

2. Frontend Terminal Studio (Port 3000)

cd frontend
npm install
npm run dev

MCP Usage (JSON-RPC 2.0)

1. List Available Tools

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }' | jq

2. Execute 3D Mesh Tool (blender_mesh)

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Google-Key: YOUR_GEMINI_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "cad_model",
      "arguments": {
        "prompt": "Precision billet aluminum impeller with keyed center bore and perimeter bolt circle",
        "format": "glb"
      }
    }
  }' | jq

3. Execute Surgical CAD Modification (cad_bisect_slice)

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "cad_bisect_slice",
      "arguments": {
        "targetMeshName": "Engine_Block",
        "planePoint": [0.0, 0.0, 0.05],
        "planeNormal": [0.0, 0.0, 1.0],
        "fillCap": true
      }
    }
  }' | jq

4. Execute Multi-Part Datum Alignment (cad_align_snap_objects)

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "cad_align_snap_objects",
      "arguments": {
        "targetMeshName": "Bearing_Ring",
        "referenceMeshName": "Shaft_Rotor",
        "alignmentMode": "STACK_TOP",
        "alignmentAxis": "z"
      }
    }
  }' | jq

5. Connect Claude Desktop / Cursor / Zed (claude_desktop_config.json)

Option A — SSE transport (no Python required):

{
  "mcpServers": {
    "kosh": {
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}

Option B — stdio bridge (works with clients that only support command/args):

{
  "mcpServers": {
    "kosh": {
      "command": "python3",
      "args": ["/path/to/Kosh/scripts/kosh_mcp_stdio.py"]
    }
  }
}

The stdio bridge (scripts/kosh_mcp_stdio.py) forwards line-delimited JSON-RPC over stdio to http://localhost:8080/mcp (override with KOSH_MCP_URL; sends X-Google-Key: $GEMINI_API_KEY when set). With the server running, the client will discover all 85 tools, 26 resources, and 19 prompts automatically on connect.

Verify the connection:

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"kosh://specs/hardware/metric-fasteners"}}' | jq

Keyboard Shortcuts Cheat Sheet

Author & Security Verification

• Project: KOSH (Minimalist Creative MCP Hub)
• Author: Sachin SureshChandra Yadav (@SachinyadavAug20)
• Event: BharatCode Build League 2026
• License: Apache 2.0 (LICENSE)
• Privacy Policy: PRIVACY.md
• M8ven Trust Index Verification:
  
• Recursive MCP Vetting: Built-in mcp_check_tool against 120,000+ indexed Model Context Protocol servers