Orsoft MCP Server

MCP (Model Context Protocol) server pro čtení dat z Orsoft informačního systému (MS SQL Server).
Určen k použití jako nástroj (Tool) v Claude Cowork pluginu.

Předpoklady

• Node.js 20+
• Přístup k MS SQL Serveru s read-only SQL účtem

Instalace

cd orsoft-mcp
npm install

Konfigurace

cp .env.example .env
# Otevřete .env a vyplňte přihlašovací údaje k SQL Serveru

| Proměnná | Popis | Výchozí | |-----------------|-----------------------------------------------|---------| | DB_SERVER | Adresa SQL Serveru (hostname nebo IP) | – | | DB_DATABASE | Název databáze | – | | DB_USER | SQL Server uživatel | – | | DB_PASSWORD | Heslo | – | | DB_PORT | Port | 1433 | | DB_ENCRYPT | Šifrovat připojení (true/false) | false | | DB_TRUST_CERT | Důvěřovat self-signed cert (jen vývoj!) | true |

Build a spuštění

npm run build      # Zkompiluje TypeScript → dist/
npm start          # Spustí MCP server (stdio transport)

Dostupné nástroje

| Nástroj | Popis | |-----------------|---------------------------------------------------------| | list_tables | Výpis tabulek a pohledů v databázi | | describe_table| Sloupce a datové typy zadané tabulky | | run_select | Spuštění SQL SELECT dotazu (max 500 řádků) |

Přidání vlastního nástroje

1. Vytvořte src/tools/muj-nastroj.ts:

import sql from "mssql";
import { query } from "../db.js";
import type { RegisteredTool } from "./index.js";

export const mojNastrojTool: RegisteredTool = {
  definition: {
    name: "get_employees",
    description: "Vrátí seznam zaměstnanců.",
    inputSchema: {
      type: "object",
      properties: {
        department: { type: "string", description: "Filtr oddělení." },
      },
    },
  },
  handler: async (args) => {
    const rows = await query(
      `SELECT TOP 100 jmeno, prijmeni, oddeleni
       FROM dbo.Zamestnanci
       WHERE (@oddeleni IS NULL OR oddeleni = @oddeleni)`,
      {
        oddeleni: { type: sql.NVarChar, value: args.department ?? null },
      }
    );
    return JSON.stringify(rows, null, 2);
  },
};

2. Zaregistrujte v src/tools/index.ts:

import { mojNastrojTool } from "./muj-nastroj.js";

export const tools: RegisteredTool[] = [
  listTablesTool,
  describeTableTool,
  selectQueryTool,
  mojNastrojTool,   // ← přidáno
];

Integrace do Claude Cowork pluginu

Viz složku ../plugin/ (bude vytvořena v dalším kroku).
V souboru plugin.json se MCP server konfiguruje jako:

{
  "mcpServers": {
    "orsoft": {
      "command": "node",
      "args": ["<cesta>/orsoft-mcp/dist/index.js"],
      "env": {
        "DB_SERVER": "${DB_SERVER}",
        "DB_DATABASE": "${DB_DATABASE}",
        "DB_USER": "${DB_USER}",
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    }
  }
}

Bezpečnost

• Server provádí pouze čtení (SELECT). DML/DDL příkazy jsou odmítnuty.
• Všechny vstupy jsou parametrizovány – ochrana před SQL injection.
• Doporučeno používat read-only SQL účet s přístupem jen k potřebným tabulkám/pohledům.
• Soubor .env nikdy necommitujte do Gitu.