@noyrax/mcp-server

Unified MCP Server for Noyrax Workspace - Orchestrates both plugins (5D Database Plugin + Documentation System Plugin) and provides centralized access for AI agents (Cursor, VS Code, Claude Desktop).

Quick Start

Installation

npm install -g @noyrax/mcp-server

Configuration

Cursor: Create .cursor/mcp-config.json:

{
  "mcpServers": {
    "noyrax": {
      "command": "noyrax-mcp-server",
      "args": ["${workspaceFolder}"]
    }
  }
}

VS Code: Add to .vscode/settings.json:

{
  "mcp.servers": {
    "noyrax": {
      "command": "noyrax-mcp-server",
      "args": ["${workspaceFolder}"]
    }
  }
}

First Steps

1. Restart Cursor/VS Code
2. Ask in Chat: "What is the system?" or "System status check"
3. The AI agent should access tools via MCP Server

See INSTALLATION_GUIDE.md for detailed setup.

Overview

Der Noyrax Unified MCP Server ist ein Root-Level MCP-Server, der beide Plugins koordiniert:

• 5D Database Plugin - Datenbank-Queries, Semantic Search, System-Analyse
• Documentation System Plugin - Dokumentations-Generierung, Validierung, Drift-Detection

Architektur

VS Code/Cursor/Copilot
    ↓ (MCP Protocol)
Root MCP-Server
    ├── Database Tools → 5D Database Plugin APIs
    ├── Validation Tools → Documentation System Plugin CLI
    └── Orchestration Tools → Workflow-Koordination

Features

Database Tools (5D Database Plugin)

• Queries: query_modules, query_symbols, query_dependencies, query_adrs, query_changes
• Semantic Search: semantic_discovery (nutzt Semantic Brain)
• System-Analyse: system_explanation, learning_path, bootstrap
• Advanced: cross_analysis, gap_analysis, architecture_mining
• Workflow: generate_documentation, check_docs_status

Validation Tools (Documentation System Plugin)

• validation/runScan - Dokumentations-Scan
• validation/runValidate - Dokumentations-Validierung
• validation/runDriftCheck - Drift-Detection
• validation/analyzeImpact - Impact-Analyse
• validation/verifyAdrs - ADR-Verification

Orchestration Tools

• workflow/full_cycle - Vollständiger Workflow (Scan → Generate → Validate → Ingest → Embeddings)
• workflow/generate_and_ingest - Generate Docs + Ingest
• workflow/check_status - System-Status prüfen

Installation

Siehe INSTALLATION_GUIDE.md für detaillierte Anleitung.

Schnellstart

# Dependencies installieren
npm install

# MCP-Server kompilieren
npm run mcp:build

# MCP-Server starten
npm run mcp:start <workspace-root>

Konfiguration

VS Code

Fügen Sie zu .vscode/settings.json hinzu:

{
  "mcp.servers": {
    "noyrax": {
      "command": "node",
      "args": [
        "${workspaceFolder}/mcp-server/out/cli/server-cli.js",
        "${workspaceFolder}"
      ]
    }
  }
}

Cursor

Fügen Sie zu .cursor/mcp-config.json hinzu:

{
  "mcpServers": {
    "noyrax": {
      "command": "node",
      "args": [
        "${workspaceFolder}/mcp-server/out/cli/server-cli.js",
        "${workspaceFolder}"
      ]
    }
  }
}

Claude Desktop

Fügen Sie zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "noyrax": {
      "command": "node",
      "args": [
        "D:/path/to/workspace/mcp-server/out/cli/server-cli.js",
        "${workspaceFolder}"
      ]
    }
  }
}

Siehe INSTALLATION_GUIDE.md für vollständige Konfiguration.

Workspace-Erkennung

Der MCP-Server unterstützt verschiedene Workspace-Konfigurationen:

• Single-Root-Workspace - Standard-Workspace
• Multi-Root-Workspace - Mehrere Workspace-Ordner
• VS Code Workspace-File - .code-workspace Dateien
• Cursor Workspace - Cursor-spezifische Konfiguration

Der Server erkennt automatisch:

• Workspace-Root
• Plugin-Pfade (5d-database-plugin/, documentation-system-plugin/)
• Dokumentations-Pfad (docs/)
• Datenbank-Pfad (.database-plugin/)

Semantic Brain Integration

Semantic Brain ist bereits vollständig integriert über das semantic_discovery Tool:

• Nutzt SemanticSearchApi aus 5D Database Plugin
• Generiert Embeddings via EmbeddingGenerator
• Speichert in Vektordatenbank (SQLite VSS oder ChromaDB)
• Keine zusätzlichen Tools nötig

Migration von alten MCP-Servern

WICHTIG: Die alten MCP-Server wurden entfernt:

• ❌ documentation-system-plugin/mcp/src/server.ts - Entfernt
• ❌ documentation-system-plugin/packages/doc-system-agent/src/mcp/server.ts - Entfernt

Neue Nutzung:

• ✅ mcp-server/ im Root-Workspace - Einheitlicher Server

Siehe INSTALLATION_GUIDE.md für Migrations-Anleitung.

Troubleshooting

Plugin nicht gefunden

Problem: "5D Database Plugin is not available" oder "Documentation System Plugin is not available"

Lösung:

1. Prüfen Sie, ob beide Plugins im Workspace existieren
2. Kompilieren Sie die Plugins: npm run compile:all
3. Prüfen Sie die Plugin-Pfade in WorkspaceResolver.findPluginPaths()

Workspace-Root nicht erkannt

Problem: Workspace-Root wird nicht korrekt erkannt

Lösung:

1. Geben Sie den Workspace-Root explizit an: npm run mcp:start <workspace-root>
2. Prüfen Sie, ob .code-workspace Dateien korrekt sind
3. Nutzen Sie absoluten Pfad für Claude Desktop

Tools funktionieren nicht

Problem: Tools geben Fehler zurück

Lösung:

1. Prüfen Sie, ob docs/ existiert (für Database-Tools)
2. Prüfen Sie, ob SQLite-DBs existieren (für Database-Tools)
3. Prüfen Sie, ob CLI-Tools kompiliert sind (für Validation-Tools)

Entwicklung

Projekt-Struktur

mcp-server/
├── src/
│   ├── server.ts                    # Haupt-MCP-Server
│   ├── workspace-resolver.ts        # Workspace-Erkennung
│   ├── cli/
│   │   └── server-cli.ts            # CLI Entry Point
│   ├── plugins/
│   │   ├── database-plugin-adapter.ts
│   │   └── documentation-plugin-adapter.ts
│   └── tools/
│       ├── database-tools.ts
│       ├── validation-tools.ts
│       └── orchestration-tools.ts
├── package.json
├── tsconfig.json
└── README.md

Build

# Kompilieren
npm run compile

# Watch-Mode
npm run watch

Testing

# MCP-Server starten (für Testing)
npm run mcp:start <workspace-root>

Weitere Informationen

• INSTALLATION_GUIDE.md - Vollständige Installations-Anleitung
• 5d-database-plugin/MCP_SERVER_SETUP.md - Database-Tools Details
• documentation-system-plugin/MCP_SERVER_SETUP.md - Validation-Tools Details

Lizenz

MIT