# VRChat Udon MCP

Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io) que expone el repositorio [agent-skills-vrc-udon](https://github.com/niaka3dayo/agent-skills-vrc-udon) como interfaz MCP para desarrollo UdonSharp en VRChat.

**El repositorio `agent-skills-vrc-udon` es la única fuente de verdad.** Este MCP no contiene documentación hardcodeada: indexa, busca y valida dinámicamente todo el contenido del repositorio.

## Características

- **18 herramientas MCP** impulsadas por el repositorio
- **Recursos MCP** dinámicos (skills, rules, cheatsheets, templates, SDK matrix)
- Indexación recursiva de `skills/`, `rules/`, `references/`, `templates/`, `hooks/`, `assets/`
- Búsqueda MiniSearch con ranking: heading > título > cuerpo
- Validación de código desde reglas del repositorio (tablas + hooks)
- File watcher con reconstrucción automática del índice
- Sincronización git del repositorio remoto
- TypeScript estricto, Vitest, ESLint, Prettier

## Requisitos

- **Node.js** 22+
- **pnpm** 9+
- **git** (para sincronizar documentación)

## Instalación

```bash
git clone https://github.com/MauDevVR/vrchat-udon-mcp.git
cd vrchat-udon-mcp
pnpm install
pnpm update-docs    # Clona/actualiza agent-skills-vrc-udon
pnpm build-index    # Construye el índice de búsqueda
pnpm build
```

## Configuración

Edita `config.json`:

```json
{
  "repository": {
    "url": "https://github.com/niaka3dayo/agent-skills-vrc-udon",
    "path": "./agent-skills-vrc-udon",
    "branch": "main"
  },
  "sdkVersion": "3.10.4",
  "language": "es",
  "watch": true,
  "indexPath": "./data/indexes",
  "search": {
    "fuzzy": 0.2,
    "headingWeight": 3.0,
    "titleWeight": 2.5,
    "exampleWeight": 1.5,
    "ruleWeight": 2.0,
    "skillWeight": 2.5,
    "cheatsheetWeight": 2.5,
    "maxResults": 20
  }
}
```

| Campo | Descripción |
|-------|-------------|
| `repository.url` | URL del repositorio fuente |
| `repository.path` | Ruta local del repositorio clonado |
| `repository.branch` | Rama a sincronizar |
| `sdkVersion` | Versión SDK por defecto para filtros |
| `watch` | Reconstruir índice al detectar cambios en el repo |
| `indexPath` | Carpeta del índice persistido |

También puedes usar la variable de entorno `UDON_MCP_CONFIG` para apuntar a otro archivo de configuración.

## Sincronización del repositorio

```bash
# Clonar o actualizar agent-skills-vrc-udon y reconstruir índice
pnpm update-docs

# Solo reconstruir índice (sin git pull)
pnpm build-index
```

El repositorio se clona en `./agent-skills-vrc-udon` (configurable). Los archivos nuevos se indexan automáticamente sin cambios de código.

## Uso

```bash
pnpm start      # Inicia el servidor MCP (stdio)
pnpm dev        # Modo desarrollo con recarga
pnpm test       # Ejecuta tests Vitest
```

## Integración con IDEs

### Cursor

En **Cursor Settings → MCP**, añade:

```json
{
  "mcpServers": {
    "vrchat-udon": {
      "command": "node",
      "args": ["C:/ruta/a/vrchat-udon-mcp/dist/index.js"],
      "env": {}
    }
  }
}
```

Asegúrate de haber ejecutado `pnpm update-docs`, `pnpm build-index` y `pnpm build` antes.

### Claude Desktop

En `%APPDATA%\Claude\claude_desktop_config.json` (Windows) o `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "vrchat-udon": {
      "command": "node",
      "args": ["/ruta/a/vrchat-udon-mcp/dist/index.js"]
    }
  }
}
```

### ChatGPT Desktop

Configura un servidor MCP stdio similar apuntando a `dist/index.js`.

## Herramientas MCP

| Herramienta | Descripción |
|-------------|-------------|
| `search_documentation` | Búsqueda keyword/fuzzy en toda la documentación |
| `explain_topic` | Explicación con citas (path, heading, líneas) |
| `list_skills` | Descubre skills automáticamente |
| `read_skill` | Lee SKILL.md con metadata, rules, references, templates |
| `list_rules` | Lista reglas UdonSharp |
| `read_rule` | Lee regla con constraints y ejemplos |
| `search_reference` | Busca en references/ |
| `list_templates` | Lista plantillas .cs |
| `get_template` | Obtiene plantilla con código completo |
| `validate_code` | Valida código con reglas del repositorio |
| `explain_validation` | Explica fallo citando la regla fuente |
| `sdk_matrix` | Matriz de versiones SDK desde templates/AGENTS.md |
| `search_sdk_feature` | Busca features (NetworkCallable, PlayerData, etc.) |
| `search_constraints` | Busca restricciones (List, Coroutine, etc.) |
| `search_networking` | Busca temas de networking y sync |
| `search_examples` | Busca ejemplos de código |
| `search_best_practice` | Busca patrones recomendados |
| `search_antipattern` | Busca anti-patrones |

## Recursos MCP

- `udon://skills/{id}` — SKILL.md de cada skill
- `udon://rules/{id}` — Archivos de reglas
- `udon://sdk/matrix` — Matriz de versiones SDK
- `udon://templates/index` — Índice de plantillas
- `udon://cheatsheet/{id}` — CHEATSHEET.md por skill

## Arquitectura

```
agent-skills-vrc-udon/     ← Fuente de verdad (git clone)
        ↓
KnowledgeParser            ← Indexa recursivamente todos los archivos
        ↓
DocsRepository             ← Persiste índice en data/indexes/
        ↓
SearchEngine (MiniSearch)  ← Búsqueda con ranking ponderado
RuleParser                 ← Reglas desde hooks/ y tablas rules/
        ↓
MCP Tools (18)             ← Interfaz para el agente IA
```

## Scripts

| Script | Descripción |
|--------|-------------|
| `pnpm build` | Compila TypeScript |
| `pnpm start` | Inicia servidor MCP |
| `pnpm test` | Tests Vitest |
| `pnpm update-docs` | git clone/pull del repositorio fuente |
| `pnpm build-index` | Reconstruye índice de búsqueda |
| `pnpm lint` | ESLint |
| `pnpm format` | Prettier |

## Créditos

- Documentación y skills: [niaka3dayo/agent-skills-vrc-udon](https://github.com/niaka3dayo/agent-skills-vrc-udon)
- Servidor MCP: [MauDevVR/vrchat-udon-mcp](https://github.com/MauDevVR/vrchat-udon-mcp)

## Licencia

MIT