SUMIT MCP — מחבר MCP למערכת סאמיט (SUMIT) עם ניהול ריבוי חשבונות

שרת Model Context Protocol שחושף את כל ה-REST API של SUMIT (הנהלת חשבונות, מסמכים, סליקת אשראי, הוראות קבע, CRM, מלאי, ניהול ארגון) לכל מנוע AI שתומך ב-MCP — Claude.ai, Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, ChatGPT ועוד.

• ריבוי חשבונות — מנהלים כמה ארגונים של סאמיט (CompanyID + APIKey לכל אחד) מקונסולת ניהול אחת; כל כלי מקבל פרמטר account, יש חשבון ברירת מחדל, וה-AI יכול לעבור בין חשבונות באמצע שיחה.

• קונסולת ניהול בעברית (/admin) — הוספת חשבונות, בדיקת חיבור, יצירת טוקנים עם הרשאות (קריאה / כתיבה / סליקה) ולפי חשבונות, ניהול חיבורי OAuth, יומן פעילות, קטלוג כלים, והוראות חיבור מוכנות להעתקה.

• 68 כלים — 63 כלים ייעודיים לכל endpoint מוכר + sumit_api_request לקריאה חופשית לכל endpoint, sumit_api_catalog, sumit_list_accounts, sumit_use_account, sumit_test_connection. אפשר להרחיב אוטומטית מקובץ ה-Swagger הרשמי.

• אבטחה — מפתחות ה-API מוצפנים במנוחה (AES-256-GCM), טוקנים נשמרים כ-hash, OAuth 2.1 מלא (PKCE + Dynamic Client Registration) עם מסך הסכמה שבו בוחרים חשבונות והרשאות, הפרדת הרשאות לפעולות שמזיזות כסף, יומן ביקורת ללא סודות.

• תחבורה — Streamable HTTP (התקן העדכני), SSE (תאימות לאחור) ו-stdio (הפעלה מקומית).

חשוב לדעת: תיעוד ה-API הרשמי של סאמיט זמין רק למשתמשים מחוברים, ולכן מבני הבקשות נבנו מספריות לקוח ציבוריות (ראו docs/SUMIT_API_COVERAGE.md). לכל כלי מצוינת רמת ביטחון; ולקבלת כיסוי מדויק ומלא מומלץ לייבא את קובץ ה-Swagger הרשמי (הוראות למטה). השרת עצמו נבדק מקצה לקצה מול שרת סאמיט מדומה — לא מול חשבון סאמיט חי.

תוכן עניינים

1. התקנה מהירה

2. הגדרת חשבונות סאמיט

3. חיבור ל-Claude ולמנועי AI

4. הרשאות, טוקנים ו-OAuth

5. הכלים

6. הרחבת הקטלוג מה-Swagger הרשמי

7. משתני סביבה

8. פריסה לענן

9. פיתוח ובדיקות

10. English summary

Related MCP server: FacturaHub MCP Server

התקנה מהירה

Docker (מומלץ)

git clone <this repo> sumit-mcp && cd sumit-mcp
cp .env.example .env            # ערכו PUBLIC_URL, MASTER_KEY (openssl rand -hex 32), ADMIN_PASSWORD
docker compose up -d --build

Node.js 20+

npm install
npm run build
PUBLIC_URL=https://sumit-mcp.example.com MASTER_KEY=$(openssl rand -hex 32) npm start

פתחו את PUBLIC_URL/admin. בכניסה הראשונה תתבקשו לקבוע סיסמת מנהל (אלא אם הגדרתם ADMIN_PASSWORD).

הגדרת חשבונות סאמיט

1. בסאמיט: הגדרות ← מפתחות API / מפתחים — העתיקו את מזהה החברה (CompanyID) ואת מפתח ה-API (הפרטי). למי שרוצה להשתמש בכלי הטוקניזציה של כרטיסים אפשר להוסיף גם את המפתח הציבורי.

2. בקונסולה: חשבונות סאמיט ← + הוספת חשבון — תנו שם ברור (למשל "העסק הראשי", "עמותה"), הזינו CompanyID ומפתח, וסמנו חשבון ברירת מחדל.

3. לחצו בדיקת חיבור — השרת קורא ל-/website/companies/getdetails/ ומציג את שם הארגון.

הוסיפו כמה חשבונות שתרצו. ה-AI פונה אליהם לפי השם/מזהה/CompanyID (account: "עמותה"), ואפשר להגביל כל טוקן או חיבור OAuth לחשבונות מסוימים.

חיבור ל-Claude ולמנועי AI

בקונסולה יש טאב "חיבור ל-Claude / AI" עם כל הקטעים מוכנים להעתקה (כולל הטוקן שיצרתם). בקצרה:

דוגמת Claude Desktop במצב stdio:

{
  "mcpServers": {
    "sumit": {
      "command": "node",
      "args": ["/path/to/sumit-mcp/dist/stdio.js"],
      "env": {
        "SUMIT_ACCOUNTS": "[{\"name\":\"העסק הראשי\",\"companyId\":123456,\"apiKey\":\"...\"},{\"name\":\"עמותה\",\"companyId\":654321,\"apiKey\":\"...\"}]"
      }
    }
  }
}

הרשאות, טוקנים ו-OAuth

• הרשאות (scopes): read (קריאה), write (יצירת/עדכון מסמכים, לקוחות, CRM, שליחת מיילים, ביטולים), payments (חיובי אשראי, זיכויים, הוראות קבע, CreditGuy). כלי שדורש הרשאה שאין לחיבור מחזיר שגיאה ברורה.

• טוקני API נוצרים בקונסולה, מוצגים פעם אחת בלבד, נשמרים כ-hash, ניתנים להגבלה לחשבונות ולתאריך תפוגה, וניתנים לביטול.

• OAuth 2.1 מופעל אוטומטית כש-PUBLIC_URL הוא https (או localhost). השרת מפרסם /.well-known/oauth-authorization-server ו-/.well-known/oauth-protected-resource/mcp, תומך ב-Dynamic Client Registration, PKCE (S256) ו-refresh tokens. במסך ההסכמה בוחרים חשבונות והרשאות; ברירת המחדל היא ללא payments.

• יומן פעילות: כל קריאת כלי (מבצע, חשבון, נתיב, תוצאה, משך) נרשמת ללא סודות.

הכלים

לכל כלי יש פרמטר account (אופציונלי) ו-extra — מפה של שדות נוספים שמתווספים לגוף הבקשה כפי שהם, כך שאפשר להעביר כל שדה מהתיעוד הרשמי גם אם אינו ממודל. הרשימה המלאה עם נתיבים ורמות ביטחון: docs/SUMIT_API_COVERAGE.md.

הרחבת הקטלוג מה-Swagger הרשמי

1. היכנסו לסאמיט והורידו את קובץ ה-OpenAPI: https://app.sumit.co.il/swagger/v1/swagger.json (או דרך Swagger UI ב-/help/developers/swagger/).

2. הריצו:

   npm run import-swagger -- ./swagger.json        # יוצר catalog/generated.json

3. הפעילו מחדש את השרת. כל פעולה בקובץ הופכת לכלי sumit_api_<module>_<controller>_<action> עם תיאור השדות מהתיעוד (כלים ייעודיים קיימים לא מוחלפים).

משתני סביבה

פריסה לענן

• DigitalOcean + CapRover (מומלץ): מדריך מלא בעברית — docs/DEPLOY_CAPROVER_DIGITALOCEAN.md. הריפו כולל captain-definition, תבנית One-Click (deploy/caprover/one-click-app.yml), מחולל משתני סביבה עם סודות (deploy/caprover/make-env.sh), סקריפט פריסה (deploy/caprover/deploy.sh) ו-GitHub Actions שמפרסם image ל-GHCR.

• Railway / Render / Fly.io / Koyeb: פרסו את ה-Dockerfile, הגדירו PUBLIC_URL=https://<your-domain>, TRUST_PROXY=1, MASTER_KEY, ADMIN_PASSWORD, וחברו נפח (volume) ל-/data.

• VPS עם Caddy: caddy reverse-proxy --from sumit.example.com --to localhost:8080 נותן https אוטומטי.

• בדיקת בריאות: GET /healthz.

פיתוח ובדיקות

npm run dev          # tsx watch
npm run typecheck
npm test             # vitest: יחידה + מקצה-לקצה (שרת סאמיט מדומה, MCP client אמיתי, OAuth מלא)

מבנה הקוד: src/core (הצפנה, אחסון, לקוח סאמיט, חשבונות) · src/mcp (קטלוג הכלים, הקשר ריבוי-חשבונות, סשנים) · src/auth (טוקנים, OAuth, מסך הסכמה) · src/admin (API + ממשק הניהול) · src/app.ts (חיבור הכל ב-Express) · src/server.ts / src/stdio.ts (נקודות כניסה).

English summary

SUMIT MCP is a Model Context Protocol server for the Israeli SUMIT business platform (accounting documents, credit-card clearing, recurring billing, CRM, stock, organisation management) with first-class multi-account support.

• Admin console (/admin, Hebrew/RTL): add SUMIT accounts (CompanyID + API key, encrypted at rest), test them, mint scoped API tokens (read / write / payments, per-account), manage OAuth grants, view an audit log and copy ready-made connection snippets.

• 68 tools: 63 curated endpoint tools (documents, customers, payments, refunds, recurring, payment methods, CreditGuy terminal, CRM schema/data/views, triggers, company/users/permissions, stock, VAT/exchange rates, bank account validation) plus sumit_api_request (any endpoint), sumit_api_catalog, sumit_list_accounts, sumit_use_account, sumit_test_connection. Every tool accepts account and extra.

• Transports: Streamable HTTP (/mcp, bearer token or /mcp/t/<token>), legacy SSE (/sse), stdio (dist/stdio.js).

• Built-in OAuth 2.1 authorization server (DCR + PKCE + refresh tokens) with a consent page for Claude.ai custom connectors, where the admin picks which accounts and scopes each connection may use.

• Extend the catalog from the official Swagger: npm run import-swagger -- swagger.json.

• Request shapes were reconstructed from public client libraries because SUMIT's docs require a login; see docs/SUMIT_API_COVERAGE.md for per-tool confidence levels. The server was verified end-to-end against a fake SUMIT API, not a live account.