SAP ABAP Agent

🏗️ Kiến trúc hệ thống

Ba tầng đơn giản: bạn hỏi trong Claude/GUI → routing + skills → MCP nói chuyện với SAP.

🌐 Biến môi trường

🐛 Báo cáo lỗi tự động (Continuous Improvement)

Error reporter chạy ngầm qua hook system, tự động phát hiện lỗi runtime (lệnh bash fail, MCP tool lỗi, activate fail...) rồi ghi file Markdown local tại %USERPROFILE%\.sap-abap-agent\error-reports\reports\ (Windows) hoặc ~/.sap-abap-agent/error-reports/reports/ (macOS/Linux). Nếu có GitHub auth, sẽ tự tạo issue để dev fix — mỗi ngày plugin càng ít lỗi hơn.

Bước 1 — Bật error reporter

Chọn 1 trong 2 cách:

Cách A — Tạm thời (chỉ session terminal hiện tại)

$env:SAP_ABAP_AGENT_ERROR_REPORTING = "1"Sao chép

set SAP_ABAP_AGENT_ERROR_REPORTING=1Sao chép

export SAP_ABAP_AGENT_ERROR_REPORTING=1Sao chép

Cách B — Vĩnh viễn (tạo file marker, không cần set env mỗi lần)

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.sap-abap-agent\error-reports"
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.sap-abap-agent\error-reports\ENABLED"Sao chép

if not exist "%USERPROFILE%\.sap-abap-agent\error-reports" mkdir "%USERPROFILE%\.sap-abap-agent\error-reports"
echo. > "%USERPROFILE%\.sap-abap-agent\error-reports\ENABLED"Sao chép

mkdir -p ~/.sap-abap-agent/error-reports && touch ~/.sap-abap-agent/error-reports/ENABLEDSao chép

Bước 2 — Kiểm tra trạng thái

Chạy lệnh sau bất kỳ lúc nào để xem số lỗi đã ghi nhận, bao nhiêu issue đã tạo trên GitHub:

"{}" | python hooks/error_reporter.py statusSao chép

echo {} | python hooks\error_reporter.py statusSao chép

echo '{}' | python hooks/error_reporter.py statusSao chép

Bước 3 — Xem file report (Markdown local, không cần GitHub)

Mỗi lỗi được save thành 1 file .md hoàn chỉnh tại ~/.sap-abap-agent/error-reports/reports/. Dù không có GitHub auth bạn vẫn đọc và share được:

Get-ChildItem "$env:USERPROFILE\.sap-abap-agent\error-reports\reports\"Sao chép

dir "%USERPROFILE%\.sap-abap-agent\error-reports\reports\"Sao chép

ls ~/.sap-abap-agent/error-reports/reports/Sao chép

Bước 4 — Tạo GitHub issue tự động (optional)

Nếu muốn error reporter tự tạo GitHub issue để dev fix, cần 1 trong 2 thứ:

• gh CLI đã login, HOẶC
• Set biến môi trường GITHUB_TOKEN (hoặc GH_TOKEN):

[System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_xxx", "User")Sao chép

setx GITHUB_TOKEN "ghp_xxx"Sao chép

echo 'export GITHUB_TOKEN=ghp_xxx' >> ~/.bashrcSao chép

Sau khi có token, chạy 1 lần để tạo 2 label cần thiết trên repo:

python reference\scripts\setup_labels.pySao chép

python reference/scripts/setup_labels.pySao chép

Lưu đồ hoạt động

User chạy lệnh → PostToolUse detect → ghi error_log.jsonl
                                           ↓
Stop hook → gom nhóm 24h → dedup (SHA256) → tạo GitHub issue (nếu mới)
                                           ↓
Khi Claude viết code sửa lỗi → detect-fix → ghi fix_log.jsonl
                                           ↓
Stop → match fix với issue → add comment "cách sửa" vào issue có sẵn
                                           ↓
Issue = [🐛 error] + [✅ fix solution] → Dev fix → release → user update → ít lỗi hơnSao chép

Các chế độ hook

➕ Thêm project SAP mới

Cách nhanh nhất — truyền URL trực tiếp:

mcp-sap-connect setup https://project1.s4hana.cloud.sapSao chép

Wizard sẽ tự sinh profile ID từ hostname (vd: project1.s4hana.cloud.sap) và hỏi phương thức xác thực (chọn 1-4):

• 1. OAuth2 (client_credentials) — client_id + client_secret, mặc định/khuyên dùng
• 2. Password — username + password
• 3. Bearer token — token có sẵn, nhập tay
• 4. Cookie-based — session cookie SAP, xem chi tiết ở mục Cookie Auth & Web Popup Re-Auth bên dưới

Sau đó hỏi thêm Region, service type (s4hc_(private) / s4hc_(public) / btp / onprem).

Thông tin được lưu riêng trong thư mục profile:

Thêm project thứ 2, thứ 3... cũng dễ dàng:

mcp-sap-connect setup https://project2.s4hana.cloud.sap
mcp-sap-connect setup https://project3.s4hana.cloud.sapSao chép

Mỗi project có profile riêng, secret riêng (mã hóa độc lập).

🔐 OAuth2 — Kết nối SAP BTP

SAP ABAP Agent hỗ trợ 3 chế độ xác thực OAuth2 để kết nối SAP BTP / S/4HANA Cloud. Tùy vào cấu hình tenant, bạn chọn chế độ phù hợp.

Luồng hoạt động

Khi bạn gọi một MCP tool (vd sap_search), hệ thống tự động:

Cấu hình OAuth2 Client trên SAP BTP

Trước khi setup, bạn cần tạo OAuth2 client trên SAP BTP cockpit:

1. Đăng nhập SAP BTP Cockpit → vào Subaccount của bạn
2. Vào menu Security > OAuth2 Client (hoặc API Clients trong các phiên bản mới)
3. Tạo client mới với Grant Type = Client Credentials
4. Ghi lại Client ID và Client Secret
5. Nếu dùng IAS (Identity Authentication), lưu ý token URL là /oauth2/token thay vì /oauth/token

Wizard Setup chi tiết

Khi chạy mcp-sap-connect setup, wizard sẽ hỏi từng thông tin:

# Bước 1: Nhập URL SAP BTP
$ mcp-sap-connect setup https://project1.s4hana.cloud.sap

# Bước 2: Chọn chế độ xác thực
? Chọn auth mode:
  1. OAuth2 (client_credentials) ← Mặc định, khuyên dùng
  2. Password (username/password)
  3. Bearer token (nhập tay)

# Bước 3a: Nếu chọn OAuth2 client_credentials
? Client ID: sb-abc123-4567-project1x-project1project1
? Client Secret: ****************
? Scope (để trống nếu không cần):

# Bước 3b: Nếu chọn Password grant
? Username: your-username
? Password: ****************
? Client ID: sb-abc123-4567-project1x-project1project1

# Bước 3c: Nếu chọn Bearer token
? Bearer Token: ****************

# Bước 4: Thông tin bổ sung
? Region: eu10
? Service type (s4hc_(private) / s4hc_(public) / btp / onprem): s4hc_(public)Sao chép

Token URL & Xử lý các hệ thống khác nhau

Mỗi hệ thống SAP có endpoint OAuth2 khác nhau. Agent tự động xác định dựa trên URL gốc, nhưng bạn có thể override nếu cần:

Override Token URL thủ công

Nếu gặp lỗi 404 /oauth/token, bạn có thể sửa trực tiếp file secrets.json:

# Mở file secrets.json (đã mã hóa, cần giải mã qua CLI)
# HOẶC chạy lại setup với đúng token URL

# Cách nhanh: chạy lại setup với flag --overwrite
mcp-sap-connect setup https://project1.s4hana.cloud.sap

# Sau đó sửa tokenUrl trong profile
# File nằm ở:
%USERPROFILE%\.mcp-sap-connect\profiles\project1.s4hana.cloud.sap\secrets.jsonSao chép

Token Lifecycle & Auto-Refresh

Agent quản lý vòng đời token hoàn toàn tự động:

🍪 Cookie Auth & Web Popup Re-Auth

Bên cạnh OAuth2, SAP ABAP Agent hỗ trợ cookie-based authentication sử dụng SAP session cookies (MYSAPSSO2, SAP_SESSIONID, sap-usercontext). Phương thức này đặc biệt hữu dụng khi bạn đã có sẵn session từ SAP GUI, Fiori Launchpad, hoặc muốn tận dụng cơ chế Single Sign-On (SSO).

⚡ Tính năng chính

🔧 CLI Wizard — Cài đặt Cookie Auth

Khi chạy sap-btp-agent setup (hoặc mcp-sap-connect setup), wizard hỏi phương thức xác thực. Cookie-based là mặc định (option 4):

# Chạy setup wizard
$ mcp-sap-connect setup https://project1.s4hana.cloud.sap

# Auth mode — mặc định 4 (Cookie)
? Chon (1-4) [4]:
  1. OAuth2 (client_credentials)  — M2M, khuyen dung khi co client
  2. Password (username/password)
  3. Bearer token
  4. Cookie-based ← mặc định

# Nguồn cookie — mặc định 1 (SAML fast-path)
? Lay cookies tu: (1) SAML fast-path  (2) Auto - mo browser  (3) File Netscape  (4) Nhap tay [1]
  → (1) SAML: nhập user/pass IAS, ~1–3s, KHÔNG mở browser — chỉ khi IAS không MFA
  → (2) Auto: Playwright mở browser (hỗ trợ MFA), tự lấy cookie
  → (3) File Netscape / (4) Nhập tay (F12 hoặc paste Netscape)

# Re-auth khi session hết hạn
? Che do re-auth khi session het han?
  (1) Manual paste
  (2) Auto (SAML fast-path neu con dung duoc, fallback browser) ← mặc định nếu chọn (1) hoặc (2) ở trên

# Hoàn tất
✅ Da tao profile 'project1.s4hana.cloud.sap' thanh cong!
  i Auth mode: cookie
  i Re-auth mode: auto
  i Nhan dien N cookies (gom MYSAPSSO2, SAP_SESSIONID, ...)Sao chép

🌐 Web Popup Re-Auth — Khi Session Hết Hạn

Khi đang code mà session SAP hết hạn (HTTP 401), agent tự động:

🔐 Nguồn cookie lần đầu & chế độ re-auth

Hai bước độc lập: (A) lấy cookie lúc setup, (B) re-auth khi hết hạn. Chọn Manual ở A không bắt buộc Manual ở B.

📦 Cài đặt Playwright (cho Auto browser)

# Wheel đã cài — thêm extra playwright + Chromium
pip install "mcp_sap_connect[playwright]"
playwright install chromium

# Hoặc dev editable trong reference/mcp-server/
pip install -e ".[playwright]"
playwright install chromium

# Setup: Cookie (4) → nguồn cookie Auto browser (2)
sap-btp-agent setup https://project1.s4hana.cloud.sapSao chép

🧠 Kiến trúc — Lấy cảm hứng từ vibing-steampunk

Cơ chế cookie re-auth được xây dựng dựa trên pattern từ vibing-steampunk (dự án ADT → MCP bridge bằng Go):

🔧 File liên quan

• reference/mcp-server/sap_btp_agent/sap/auth.py — SapCookieAuth, ReauthHandler, ReauthStampedeGuard, web_login_popup(), web_login_auto()
• reference/mcp-server/sap_btp_agent/sap/client.py — SapClient với 401 → re-auth flow + cookie support
• reference/mcp-server/sap_btp_agent/cli/__init__.py — CLI wizard với option 4 (Cookie-based)
• reference/mcp-server/sap_btp_agent/config/store.py — reauthMode config field

⚠️ Lưu ý

🔌 Kiểm tra kết nối

Sau khi thêm project, kiểm tra profile trước khi dùng MCP. Entry point chính thức là mcp-sap-connect; sap-btp-agent vẫn là shim tương đương.

# Ping nhanh — chỉ đọc session (nhẹ, không xin CSRF/write)
mcp-sap-connect ping
sap-btp-agent ping

# Connect đầy đủ — đọc + kiểm tra ghi (CSRF). Dùng trước activate / list_packages…
mcp-sap-connect connect
mcp-sap-connect connect project1.s4hana.cloud.sap

# Cookie hết hạn — đăng nhập lại (nhanh hơn setup từ đầu)
mcp-sap-connect reauth
mcp-sap-connect reauth project1.s4hana.cloud.sap

# Môi trường máy (PATH, dependency) — không cần profile
mcp-sap-connect doctor
# Nếu lệnh không nhận diện được:
python -m mcp_sap_connect.doctorSao chép

👥 Quản lý nhiều profile

Mỗi URL SAP = 1 profile (secrets riêng). Entry chính: mcp-sap-connect (sap-btp-agent = shim cùng lệnh).

Chọn profile trong MCP tools

Thứ tự ưu tiên: env SAP_BTP_PROFILE → tham số profile trên tool → profile active.

"Liệt kê package trên project1"
→ sap_list_packages({ profile: "project1.s4hana.cloud.sap" })

"Tìm ZCL_* trên profile đang active"
→ sap_search({ query: "ZCL_" })  # không truyền profileSao chép

Chạy nhiều instance cùng lúc

Gắn profile khác nhau cho mỗi process MCP (env ghi đè active):

# Terminal A — profile project1
SAP_BTP_PROFILE=project1.s4hana.cloud.sap mcp-sap-connect

# Terminal B — profile khác
SAP_BTP_PROFILE=project2.s4hana.cloud.sap mcp-sap-connectSao chép

# Terminal A
$env:SAP_BTP_PROFILE = "project1.s4hana.cloud.sap"
mcp-sap-connect

# Terminal B
$env:SAP_BTP_PROFILE = "project2.s4hana.cloud.sap"
mcp-sap-connectSao chép

⚙️ Đăng ký MCP với Claude Code

Claude Code không còn dùng file mcp_servers.json — đăng ký bằng lệnh claude mcp add:

claude mcp add --transport stdio sap-connect -- mcp-sap-connectSao chép

Mặc định scope local (chỉ máy này, chỉ project hiện tại). Dùng --scope user để dùng được ở mọi project, hoặc --scope project để lưu vào .mcp.json và chia sẻ qua git cho cả team.

💡 Notion — skill notes dùng chung cho team. Server notion đã auto-bundle sẵn trong .mcp.json của plugin này — không cần claude mcp add thủ công. Mỗi thành viên chỉ cần gõ /mcp trong Claude Code để đăng nhập tài khoản Notion của chính mình (OAuth, không lưu token nào trong repo). Chia sẻ workspace cho team = mời thành viên vào page Notion tương ứng (thao tác phía Notion), không liên quan đến file cấu hình.

Test plugin cục bộ (không cần cài vào marketplace):

claude --plugin-dir ./sap-abap-agentSao chép

🔄 Cập nhật

Có 2 cơ chế cập nhật tự động — chạy 1 lệnh là xong:

# Windows (PowerShell)
.\reference\scripts\update.ps1

# Linux / macOS
bash reference/scripts/update.sh

🛠️ MCP Tools

Sau khi đăng ký, các tool sau sẽ xuất hiện trong Claude Code. Mỗi tool đều có tham số profile (để trống = dùng profile active).

Ví dụ prompt trong Claude Code:

"Liệt kê tất cả profile SAP của tôi"
→ Claude gọi sap_list_profiles()

"Tìm class bắt đầu bằng ZCL_ trong project project1"
→ Claude gọi sap_search({ profile: "project1.s4hana.cloud.sap", query: "ZCL_" })Sao chép

⌨️ Lệnh CLI

Tips: Bạn có thể dùng lệnh /sap-connect ngay trong Claude Code để được hướng dẫn từng bước. Nếu mcp-sap-connect báo "not recognized", chạy python -m mcp_sap_connect.doctor — lệnh này chạy được dù PATH chưa đúng.

🧠 SAP Consultant System (28 agents)

skills/sap-ask-consultant/SKILL.md — Auto-scoring routing engine dispatch câu hỏi user tới 28 agents (25 module consultants + 1 researcher + 1 daily learner + 1 reviewer).

🔀 Cách hoạt động

1. Keyword Matrix: Mỗi module có keywords với weight 3/2/1
2. Tính score: Module >= threshold (2) → dispatch
3. Explicit mention: "hoi SD", "hoi FI" → dispatch mặc định
4. Module coupling: FI↔CO, PP→QM→MM, PM→MM→FI, v.v.
5. Parallel dispatch: Tất cả module >= threshold dispatch song song

Danh sách 28 agents (25 module consultants + 3 cross-cutting)

Ví dụ routing

🔀 Auto-scoring Routing Engine

Chi tiết keyword matrix, explicit mention, module coupling xem trong file skills/sap-ask-consultant/SKILL.md.

📚 Bước 5 — tra kiến thức có sẵn trước khi dispatch: trước khi giao cho agent tư vấn trả lời, routing tự tra memory/procedural/skills/ (local, offline) rồi tới database "SAP Skills" trên Notion (online, chỉ khi local chưa có) — thấy thì dùng luôn + tự cache lại local, không thấy thì agent trả lời như bình thường. Mất local (đổi máy...) không sao, lần hỏi lại đầu tiên sẽ tự lấy lại từ Notion. Áp dụng cho toàn bộ 25 agent tư vấn, không chỉ Daily Learner.

Keyword Matrix (rút gọn)

Module Coupling chính

📇 Chi tiết từng Agent (28 files)

28 agents — 25 module consultants (auto-scored, parallel dispatch) + 1 docs researcher (tra cứu CDS/docs) + 1 daily learner (học SAP mỗi ngày) + 1 abap-reviewer (review code). Mỗi agent chỉ tư vấn/review — không tự sửa code (không Write/Edit), chạy model sonnet.

💡 Cách đặt câu hỏi hiệu quả

Hệ thống sử dụng auto-scoring routing engine để tự động dispatch câu hỏi tới đúng consultant. Cách bạn đặt câu hỏi ảnh hưởng trực tiếp đến độ chính xác của routing.

📝 Nguyên tắc chung

• Dùng từ khóa chuyên ngành: "purchase order" thay vì "đơn mua", "cost center" thay vì "bộ phận"
• Nói rõ module: "SD: pricing cho sales order" — dùng "hoi X:" để force dispatch module X
• Hỏi một vấn đề / lần: Hệ thống dispatch song song, nhưng câu hỏi quá rộng sẽ làm loãng score
• Dùng tiếng Anh cho keywords: Từ khóa weight-3 đều là tiếng Anh (sales order, GL, purchase order...)

🎯 Mẫu câu hỏi cho từng module

🔗 Câu hỏi multi-module (dispatch song song)

💬 Câu hỏi cho từng skill

⚡ Mẹo nâng cao

💬 Bắt đầu ngay

Mở Claude Code với plugin và thử một trong các câu lệnh sau:

📚 Học SAP mỗi ngày — Hermes-like Agent

skills/sap-daily-learner/SKILL.md — Agent tự cải thiện (self-improving) lấy cảm hứng từ Hermes Agent bởi Nous Research. Vừa là gia sư SAP hàng ngày, vừa tự động tạo skill documents từ tương tác với người dùng.

🌟 Hai chế độ hoạt động

🧠 Hermes-like Features

🧹 Skill Curator — vòng đời skill tự động

Skill tự tạo trong memory/procedural/skills/ càng tích luỹ càng dễ "chết" — không còn ai dùng nhưng vẫn nằm mãi. reference/scripts/skill_curator.py xử lý việc này, đúng cơ chế Curator của Hermes: skill không dùng tới sau 30 ngày chuyển stale, sau 90 ngày chuyển archived (di chuyển vào .archive/, không bao giờ xoá thật). Dùng lại 1 skill sẽ tự đưa nó về active. Chạy tự động mỗi khi sap-daily-learner được gọi — không cần setup gì thêm.

⏰ Cron thật — daily tip chạy nền qua Windows Task Scheduler

Khác Hermes bản gốc (có gateway daemon chạy liên tục, tự poll mỗi 60 giây): plugin này không có tiến trình nền thật — dùng Windows Task Scheduler làm "cái luôn túc trực" thay cho daemon đó.

Bước 1 — Cài lịch Task Scheduler (chưa chạy gì, cần quyền Administrator)

Click phải reference\scripts\install-daily-learner-cron.bat → Run as administratorSao chép

Sau khi cài, task sẽ tự "tick" mỗi 5 phút nhưng vẫn no-op (không làm gì) cho tới Bước 2.

Bước 2 — Bật opt-in thật sự

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.sap-abap-agent\cron"
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.sap-abap-agent\cron\ENABLED"Sao chép

if not exist "%USERPROFILE%\.sap-abap-agent\cron" mkdir "%USERPROFILE%\.sap-abap-agent\cron"
echo. > "%USERPROFILE%\.sap-abap-agent\cron\ENABLED"Sao chép

Hoặc set biến môi trường hệ thống SAP_ABAP_AGENT_CRON_ENABLED=1 thay vì tạo file marker — 2 cách tương đương.

Bước 3 — Thêm ít nhất 1 job

python reference\scripts\cron_manage.py add "$env:USERPROFILE\.sap-abap-agent" daily-tip "/sap-daily-learner cho toi 1 tip hoc SAP hom nay dua tren tien do hien tai" daily@08:00Sao chép

Kiểm tra trạng thái / chi phí đã dùng

python reference/scripts/cron_manage.py status "$(python reference/scripts/agent_home.py)"Sao chép

Kết quả tick được ghi vào <agent-home>/cron/pending/, rồi tự bơm vào phiên chat Claude Code kế tiếp khi bạn mở lên (SessionStart hook hooks/cron_deliver.py) — không có tích hợp Telegram/Slack như Hermes thật, nhưng không cần thêm thao tác nào.

Gỡ bỏ: schtasks /delete /tn "SAP ABAP Agent - Daily Learner Cron Tick" /f, xoá file ENABLED/cron_manage.py disable <job-id> là đủ.

📋 User Commands

👥 Chia sẻ database "SAP Skills" cho team

Mời thêm người: (1) accept invite/mở link share Notion trước (thao tác tay), (2) người đó tự /mcp connect Notion bằng tài khoản của chính họ — không dùng chung tài khoản.

📚 Module Knowledge Matrix

18 module SAP với nội dung học theo 3 trình độ. Mỗi module có 5 topics cho mỗi level.

📝 Daily Tip Templates

Mỗi ngày, Daily Learner gửi tip phù hợp với trình độ của bạn:

🎯 Progressive Learning Paths

Beginner Path (cho người mới — 4 tuần):

Intermediate Path (cho người đã biết SAP):

• Chọn 1 module chuyên sâu + 2 module liên quan
• Ví dụ: MM advanced + FI (valuation) + SD (stock transport)
• Ví dụ: PP advanced + MM (BOM/component) + QM (inspection)
• Ví dụ: FI advanced + CO (cost center) + TR (cash management)

Expert Path (cho chuyên gia — cross-module integration):

🤖 Auto-Skill Creation Engine

Khi bạn giải quyết vấn đề SAP phức tạp, Daily Learner tự động tạo skill document nếu:

📚 CDS Knowledge Base (cds-kb-mcp)

skills/sap-cds-kb/SKILL.md — Tra cứu 7,355 CDS views released cho SAP S/4HANA Cloud Public Edition qua MCP server cds-kb-mcp (host remote, không cần cài local).

5 tools

Module aliasing (dùng tên tự nhiên thay vì code SAP)

💡 Lưu ý: CDS view không phải released API — chỉ là định nghĩa view. Luôn kiểm tra thêm trên api.sap.com nếu cần xác nhận 1 view có được phép dùng trong ABAP Cloud hay không. Dữ liệu được cache local (ETag-based), có thể out-of-date so với release mới nhất.

📖 SAP Docs Research (mcp-sap-docs)

skills/sap-docs-research/SKILL.md — Tra cứu tài liệu SAP tổng hợp qua MCP server mcp-sap-docs-btp: SAP Help, SAP Community, Accelerator Hub, Fiori App Reference Library, Clean Core Released Objects, ABAP feature matrix.

💡 Lưu ý: SAP-API-HUB-KEY không bắt buộc (thiếu thì chỉ giới hạn sap_accelerator_hub_*). Offline docs có thể không phản ánh release mới nhất (SAP ra 4 bản/năm). sap_search_objects chỉ trả về released objects — không xuất hiện nghĩa là chưa release cho ABAP Cloud.

📝 SAP Notes MCP (mcp-sap-notes)

reference/mcp-guides/mcp-sap-notes.md — Tra cứu SAP Notes qua MCP server mcp-sap-notes bởi marianfoo. Tìm kiếm và đọc nội dung SAP Notes trực tiếp từ Claude Code.

Cài đặt

# Cài qua npm
npm install -g mcp-sap-notes

# Hoặc chạy trực tiếp
npx @marianfoo/mcp-sap-notesSao chép

Cấu hình Claude Code

claude mcp add --transport stdio sap-notes -- npx @marianfoo/mcp-sap-notesSao chép

Tools

💡 Hữu ích khi cần check SAP Note cho lỗi runtime, security patch, hoặc hướng dẫn cấu hình mới nhất.

🖥️ SAP GUI MCP (mcp-sap-gui)

reference/mcp-guides/mcp-sap-gui.md — Tự động hóa SAP GUI qua MCP. Điều khiển SAP GUI Windows để đọc dữ liệu, thao tác transaction, snapshot màn hình. (Hướng dẫn cài đặt tham chiếu từ agent sap-docs-researcher, không còn là skill tự trigger riêng.)

Cài đặt

# Cài qua uvx (khuyên dùng)
uvx mcp-sap-gui[screenshots]

# Hoặc pip
pip install mcp-sap-gui[screenshots]Sao chép

Cấu hình Claude Code

# Tạo file .env với SAP GUI config
SAPGUI_USER=your_user
SAPGUI_PASS=your_pass
SAPGUI_CLIENT=100
SAPGUI_LANGUAGE=EN

# Đăng ký MCP server
claude mcp add --transport stdio sap-gui -- uvx mcp-sap-guiSao chép

Tools (57 tools)

💡 Chạy uvx mcp-sap-gui lần đầu sẽ tự động cài SAP GUI Scripting API. Bảo mật: chỉ chạy trong session riêng, hỗ trợ blocklist field nhạy cảm.

🔧 ADT MCP Servers (3 options)

reference/mcp-guides/mcp-sap-adt.md — 3 lựa chọn MCP server cho SAP ADT (ABAP Development Tools) integration. Hỗ trợ đọc/ghi source ABAP trực tiếp từ ADT. (Hướng dẫn cài đặt tham chiếu từ agent sap-docs-researcher, không còn là skill tự trigger riêng.)

Option 1: SAP Official MCP Server (GA Q2 2026)

MCP server chính thức từ SAP, shipped với ADT. Tích hợp sẵn trong SAP Business Application Studio và ADT.

# Cài đặt qua SAP BTP
npm install -g @sap/adt-mcp-server

# Cấu hình
claude mcp add --transport stdio sap-adt -- @sap/adt-mcp-server --url <ADT_URL>Sao chép

Option 2: ARC-1 (Enterprise MCP cho ADT)

arc-mcp/arc-1 — Enterprise-grade MCP bridge cho ADT, hỗ trợ ABAP Cloud development workflow.

# Cài qua pip
pip install arc-mcp

# Cấu hình
claude mcp add --transport stdio arc-adt -- arc-mcp-adtSao chép

Option 3: mcp-abap-adt (cộng đồng)

mario-andreschak/mcp-abap-adt — MCP server mã nguồn mở cho ADT, 7 tools cốt lõi.

# Cài qua npm
npx @mario-andreschak/mcp-abap-adt

# Cấu hình
claude mcp add --transport stdio abap-adt -- npx @mario-andreschak/mcp-abap-adtSao chép

So sánh 3 options

👥 SuccessFactors MCP (mcp-sap-successfactors)

reference/mcp-guides/mcp-sap-successfactors.md — 2 options de tich hop SAP SuccessFactors voi AI assistant: sf-mcp (open-source, 62+ tools) va CData SF MCP (SQL-based read-only). (Hướng dẫn cài đặt tham chiếu từ agent sap-docs-researcher, không còn là skill tự trigger riêng.)

Option 1: sf-mcp (Open-source, khuyen dung)

# Yeu cau: Python 3.10+, uv package manager
git clone https://github.com/aiadiguru2025/sf-mcp.git
cd sf-mcp
uv syncSao chép

Cau hinh

claude mcp add --transport stdio sf-mcp -- uv --directory /path/to/sf-mcp run main.pySao chép

Tools (62+ tools)

💡 Option 2: CData SF MCP (Java-based, SQL read-only, can CData JDBC driver license). Xem chi tiet trong reference/mcp-guides/mcp-sap-successfactors.md.

✈️ SAP Concur MCP (mcp-sap-concur)

reference/mcp-guides/mcp-sap-concur.md — CData SAP Concur MCP Server cho phep query Travel & Expense data (expense reports, travel requests, bookings, vendors) qua SQL. Read-only, Java-based.

Cai dat

# Yeu cau: Java 11+, Maven
git clone https://github.com/CDataSoftware/sap-concur-mcp-server-by-cdata.git
cd sap-concur-mcp-server-by-cdata
mvn clean installSao chép

Cau hinh

claude mcp add --transport stdio sap-concur -- java -jar /path/to/CDataMCP-jar-with-dependencies.jar /path/to/sap-concur.prpSao chép

Tools

💡 Yeu cau CData JDBC Driver for SAP Concur (trial available). Query expense reports, travel requests, bookings, vendor data truc tiep tu AI.

🛠️ Fieldglass MCP (mcp-sap-fieldglass)

reference/mcp-guides/mcp-sap-fieldglass.md — CData SAP Fieldglass MCP Server cho phep query Services Procurement data (contingent workforce, SoW, timesheets, invoices) qua SQL. Read-only, Java-based.

Cai dat

# Yeu cau: Java 11+, Maven
git clone https://github.com/CDataSoftware/sap-fieldglass-mcp-server-by-cdata.git
cd sap-fieldglass-mcp-server-by-cdata
mvn clean install

# License JDBC Driver
java -jar cdata.jdbc.sapfieldglass.jar --licenseSao chép

Cau hinh

claude mcp add --transport stdio sap-fieldglass -- java -jar /path/to/CDataMCP-jar-with-dependencies.jar /path/to/sap-fieldglass.prpSao chép

Tools

💡 Yeu cau CData JDBC Driver for SAP Fieldglass (trial available). Query contingent workforce, Statement of Work, timesheets, invoices truc tiep tu AI.

🧭 Service Type Context (sap-service-type-context)

reference/process/sap-service-type-context.md — Xác định hệ thống đang làm việc là s4hc_(private) / s4hc_(public) / btp / onprem bằng cách đọc profiles/<id>/config.json của mcp-sap-connect (offline, không gọi MCP, không đụng secret) — hỏi user nếu chưa xác định được — trước khi trả lời câu hỏi bị ảnh hưởng bởi edition.

So sánh nhanh theo Service Type

⚠️ Không đổi theo edition: quy ước namespace Z/Y áp dụng cho mọi edition kể cả on-premise — không phải đặc thù ABAP Cloud.

Cách xác định (offline, không cần hệ thống đang sống)

Đọc thẳng profiles/<id>/config.json (field không nhạy cảm — secret nằm riêng ở secrets.json đã mã hóa) thay vì gọi sap_ping: rẻ hơn (không round-trip mạng), không phụ thuộc hệ thống SAP đang sống hay không.

python "${CLAUDE_PLUGIN_ROOT}/reference/scripts/detect_service_type.py"Sao chép

💡 Tích hợp: sap-routing-discipline trỏ tới skill này trước khi trả lời câu hỏi bị ảnh hưởng bởi edition; sap-ask-consultant/sap-extensibility/sap-clean-code/sap-abap-sql đọc kết quả để rẽ nhánh hoặc chèn cảnh báo thay vì mặc định Public Edition.

🧹 Clean Code & Name Conversion

skills/sap-clean-code/SKILL.md — Naming conventions & clean code cho ABAP Cloud (Public Cloud), kèm hướng dẫn chuyển đổi từ legacy ABAP.

Quy tắc bắt buộc

• Mọi development object customer tạo bắt buộc bắt đầu bằng Z/Y (hoặc namespace /prefix/ đã đăng ký với SAP).
• Giới hạn 30 ký tự cho mọi development object (class, CDS view, data element...).
• ABAP chỉ hỗ trợ ASCII — không dùng tiếng Việt có dấu trong tên.
• Bỏ Hungarian notation hoàn toàn (thay đổi lớn nhất so với legacy ABAP).

Bỏ Hungarian notation

CDS View — 5 layer VDM (Virtual Data Model)

Released API — quy tắc bắt buộc (Clean Core)

ABAP Cloud không thể gọi trực tiếp unreleased API — trình biên dịch sẽ báo lỗi. Kiểm tra API State trong ADT (🟢 Released / 🟡 Deprecated / 🔴 Unreleased) trước khi dùng bất kỳ class/BAPI/function module nào. Nếu bắt buộc phải dùng unreleased API, tạo wrapper class đánh dấu @deprecated thay vì gọi trực tiếp.

🧩 Extensibility Ladder & ABAP Cloud Constraints

skills/sap-extensibility/SKILL.md — Xác định nên đặt custom logic ở đâu (SSCUI/Key User/side-by-side BTP) và ràng buộc cú pháp ABAP Cloud.

4 bậc thang Extensibility (luôn đánh giá từ trên xuống)

1. Cấu hình chuẩn qua SSCUI — chỉ là 1 switch/setting SAP có sẵn.
2. Key User Extensibility (in-app, không cần dev) — Custom Fields and Logic, Custom Business Objects, Custom Logic (Cloud BAdI), Adaptation Transactions.
3. Developer Extensibility (on-stack) — chỉ có trên 3-system landscape, vẫn chỉ dùng released API/extension point.
4. Side-by-side trên BTP — hệ thống/runtime riêng (BTP ABAP Environment/RAP), gọi ngược lại core qua released API.

⚠️ Nguyên tắc fail-fast: nếu 1 yêu cầu không khớp bậc nào trong 4 bậc trên — không bịa ra cách làm không tồn tại, nói thẳng là chưa làm được.

Cú pháp bị cấm trên ABAP Cloud

📁 2-system vs 3-system landscape: đa số khách hàng Public Cloud là 2-system (chỉ Key User + side-by-side); 3-system có thêm Development tenant → mở khóa Developer Extensibility. Khi không chắc, mặc định giả định 2-system.

🛠️ Key User Toolkit

skills/sap-key-user-toolkit/SKILL.md — Hướng dẫn thực hành Key User Extensibility (bậc 2 trong thang extensibility) — tự làm không cần developer.

4 tác vụ hay gặp nhất

Quy trình release (2-system landscape)

Tạo/sửa trên Customizing tenant → test bằng test plan SAP → Export Software Collection → Import Software Collection vào Production → Activate → verify bằng user thật.

⚠️ Lưu ý: sau khi publish, custom field không thể xóa, chỉ có thể tắt qua Usage. Đặt tên nhất quán theo prefix (YY_/Z_) để tránh trùng với extension của team khác trong cùng tenant.

🔌 SAP BTP Setup Helper (multi-profile)

skills/sap-btp-setup/SKILL.md — Setup & xử lý sự cố kết nối SAP BTP qua MCP, hỗ trợ nhiều project SAP cùng lúc (multi-profile).

Thêm project mới chỉ 1 lệnh: mcp-sap-connect setup https://project1.s4hana.cloud.sap — wizard tự sinh profile, hỏi phương thức xác thực.

4 phương thức xác thực

13 MCP tools

sap_list_profiles, sap_ping, sap_list_packages, sap_search, sap_read_source, sap_syntax_check, sap_activate, sap_find_where_used, sap_execute_query, sap_run_unit_tests, sap_get_system_info, sap_analyze_dump — mỗi tool đều nhận tham số profile (để trống = active).

💡 Xử lý sự cố nhanh: lỗi 'mcp-sap-connect' is not recognized (Windows, hay gặp nhất) → chạy python -m mcp_sap_connect.doctor để tự phát hiện và lấy lệnh fix PATH.

📄 Doc to Markdown (Word/Excel → .md)

skills/sap-doc-to-md/SKILL.md — Convert file Word (.docx)/Excel (.xlsx/.xls) sang Markdown để làm ngữ cảnh cho AI đọc hiểu tài liệu nghiệp vụ (Functional Spec, Business Process...) và hỗ trợ sinh code/logic ABAP.

⚠️ Lưu ý quan trọng: mã nghiệp vụ SAP (Material, Plant, Order...) thường có số 0 đứng đầu — luôn đối chiếu vài mã sau khi convert Excel để chắc chắn không bị đổi định dạng số.

📋 Released ABAP Classes (sap-released-classes)

skills/sap-released-classes/SKILL.md — Catalog cac ABAP Cloud released classes va APIs. Nguon tham khao nhanh de tra cuu class/interface co san cho ABAP Cloud development.

🗃️ ABAP SQL & AMDP (sap-abap-sql)

skills/sap-abap-sql/SKILL.md — ABAP SQL nang cao: Window Functions, CTE, AMDP, performance patterns, CDS Table Function. Cac cau truy van bi cam tren ABAP Cloud.

🔌 Cloud BAdI Enhancement (sap-badi-enhancement)

skills/sap-badi-enhancement/SKILL.md — Cloud BAdI architecture: BAdI definition, BAdI implementation, enhancement spot, Custom Logic (Key User), BAdI filtering.

🛡️ Authorization & DCL (sap-authorization)

skills/sap-authorization/SKILL.md — ABAP Cloud authorization concept: DCL (Data Control Language), RAP instance-based authorization, IAM App, Business Role.

🔄 Cloud Migration (sap-cloud-migration)

skills/sap-cloud-migration/SKILL.md — Huong dan 5-buoc migration tu ECC on-premise len S/4HANA Cloud: ATC check, replacement strategy, modification adjustment, custom code migration.

🌐 OData Service (sap-odata-service)

skills/sap-odata-service/SKILL.md — RAP-based OData V4 service: service definition, service binding, OData metadata, ETag, deep insert, function import, action.

📨 RAP Business Events (sap-rap-events)

skills/sap-rap-events/SKILL.md — RAP business events: event definition, event metadata, event publishing, event consumption, Cloud Events format, SAP Event Mesh integration.

☁️ Steampunk / BTP ABAP (sap-steampunk-cloud)

reference/modules/sap-steampunk-cloud/SKILL.md — BTP ABAP Environment (Steampunk) infrastructure: package structure, ADT, IAM, git-based CI/CD, Cloud Foundry deployment, MTA. (Tài liệu tham chiếu cho agent sap-btp-admin-consultant-cloud, không còn là skill tự trigger riêng.)

🔗 BTP Connectivity (sap-btp-connectivity)

reference/modules/sap-btp-connectivity/SKILL.md — Cloud Connector, destination configuration (Basic, OAuth2SAMLBearer, PrincipalPropagation), RFC/BAPI access tu BTP to S/4HANA on-prem.

✅ BTP Best Practices (sap-btp-best-practices)

reference/modules/sap-btp-admin-cloud/deep/SKILL.md — BTP development conventions: account structure, naming conventions, MTA, security, CI/CD setup, CAP best practices, logging/monitoring.

🏗️ Codegen Pipeline — Function Spec → ABAP code

7 skill nối tiếp nhau, biến 1 file Function Spec (.docx khách hàng gửi) thành code ABAP scaffold theo chuẩn RAP/CDS. File trung gian đặt trong in//out/ — thư mục local per-user, không nằm trong git repo: %USERPROFILE%\.mcp-sap-connect\in\ + ...\out\ (Windows) hoặc ~/.mcp-sap-connect/in/ + .../out/ (macOS/Linux) — cùng nơi lưu profile/secrets kết nối SAP BTP. Lý do: tài liệu FS và output sinh ra là dữ liệu nghiệp vụ/khách hàng, không nên nằm chung với source code plugin.

Bước nào làm gì

🔗 Skill phụ trợ sap-virtual-element (calculated field trong CDS) dùng bổ sung ở bước 3 khi cần field tính runtime. Quy ước đặt tên & bậc thang extensibility dùng chung với Clean Code & Naming / Extensibility Ladder. 🔗 Có sẵn SEGW OData V2 cần nâng cấp? Dùng sap-migrate-segw-to-rap để reverse-engineer sang RAP thay vì scaffold lại từ đầu.

🎯 Quy trình theo mục tiêu đầu ra: Báo cáo / API / Form

Cùng xuất phát từ 1 file FS.docx/Excel, nhưng đầu ra khác nhau (báo cáo, API, form Fiori) thì rẽ nhánh skill khác nhau ở giữa pipeline. Làm đúng theo thứ tự 1 trong 3 quy trình dưới đây — không bỏ bước (*) trừ khi ghi rõ "tuỳ chọn" — là ra đủ end-to-end, không cần tự suy luận thêm bước nào.

💡 Bước 2a/2b (sap-ask-consultant) xuất hiện trong cả 3 quy trình dưới đây — đây là chỗ 2 "AI" trao đổi với nhau: 1 bên viết Technical Spec, 1 bên là chuyên gia nghiệp vụ theo phân hệ (SD/FI/MM/...). Mục đích: giảm lỗi chọn sai CDS view/field/object do chỉ dựa vào suy luận kỹ thuật thuần, không có góc nhìn nghiệp vụ thật — hỏi 1 lần để chọn nguồn, xác nhận lại 1 lần trước khi chốt.

🔒 Bước 2c (sap-deployment-target) hỏi 1 lần duy nhất xem deploy vào package nào trên hệ thống thật (có sẵn hoặc tạo mới package Z), rồi tái sử dụng cho toàn bộ pipeline — tránh phải hỏi lại nhiều lần giữa chừng. Từ bước này trở đi, quy tắc cứng áp dụng xuyên suốt: không bao giờ tạo/sửa/xoá object ngoài namespace Z/Y hoặc ngoài package đã xác nhận; chỗ nào cần thao tác thủ công (approve transport, đăng nhập, activate khi chưa nối MCP...) thì dừng lại, mô tả rõ việc cần làm, và chỉ tiếp tục sau khi có xác nhận từ người dùng. Cách xác minh package ở Bước 2c cũng khác nhau theo chế độ tích hợp: có MCP ADT thì verify tồn tại + đúng namespace customer qua tool thật; không có MCP (ví dụ workflow abapGit clone-về-local) thì hỏi user xác nhận trực tiếp, ghi rõ trong TECHNICAL_SPEC.md là "chưa verify tự động" để sap-finish-ticket đối chiếu lại sau. Ở chế độ không-MCP, hàng rào kỹ thuật (hook chặn tool MCP) cũng không phủ được thao tác ghi file abapGit local — kỷ luật hỏi-xác-nhận này là tuyến phòng thủ duy nhất.

🅰️ Báo cáo (list/detail hoặc KPI dashboard)

💡 Xem trên Fiori Elements (List Report/Analytical List Page) tự sinh từ CDS + annotation — không cần code UI riêng, chỉ cần publish Service Definition/Binding ở bước 3 là đủ. Cần in PDF/xuất file thay vì xem online? Xem pattern @Semantics.largeObject trong sap-scaffold-rap.

🅱️ API (OData service cho hệ thống/app khác gọi, CRUD hoặc read-only)

🅲️ Form chức năng (Fiori app CRUD cho end-user)

Form luôn cần 1 API/RAP BO bên dưới để CRUD — làm toàn bộ bước 0-9 của quy trình API ở trên (bỏ qua bước 10 sap-finish-ticket — để dành đến cuối, sau khi UI xong), rồi tiếp tục:

💡 Không có developer / chỉ cần thay đổi đơn giản? Bỏ qua toàn bộ quy trình trên, dùng sap-key-user-toolkit — key user tự thêm Custom Field, tạo Custom Business Object, viết Custom Logic (Cloud BAdI đơn giản), hoặc sửa giao diện qua Adaptation Transaction, hoàn toàn không cần ABAP developer.

📁 Cấu trúc thư mục

Project

Cấu hình (User folder)

• Windows: secrets mã hóa bằng DPAPI (gắn với tài khoản Windows)
• macOS/Linux: AES-256-GCM, key derive từ hostname + username
• File mode 0o600, chỉ owner đọc/ghi

Cấu hình (State của plugin — khác folder trên)

Lưu ý: đây là 2 folder tách biệt tên gần giống nhau — .mcp-sap-connect\ lưu profile kết nối SAP BTP (MCP server), còn .sap-abap-agent\ lưu state riêng của plugin Claude Code (memory học tập, cache, session đang làm). Mặc định luôn ghi vào %USERPROFILE% dù đang mở project SAP nào; override qua SAP_ABAP_AGENT_HOME khi dev/test plugin. Chi tiết: CONTRIBUTING.md.

⚠️ Lỗi thường gặp

🤝 Đóng góp cho dự án

SAP ABAP Agent là dự án open-source (MIT License). Mọi đóng góp đều được chào đón — dù là sửa lỗi chính tả, thêm skill mới, cải thiện documentation, hay báo cáo lỗi bảo mật.

Trước khi đóng góp, vui lòng đọc các tài liệu sau:

Xem thêm GitHub Repository để biết chi tiết.

🐙 About GitHub (Actions, Pages, Releases)

GitHub là nơi lưu trữ source code, chạy CI/CD tự động và phát hành bản cập nhật cho plugin này. Nếu bạn chưa từng dùng GitHub, đây là 4 khái niệm cốt lõi bạn sẽ gặp:

🛠️ Workflows đang chạy trong repo này

🚀 Bắt đầu nhanh với GitHub (cho SAP consultant)

1. Tạo tài khoản miễn phí tại github.com/signup — chỉ cần email.
2. Xem source trên web: mở link repo ở trên, nhấn phím . (dấu chấm) để mở VS Code online, hoặc > để vào GitHub Codespaces (IDE cloud).
3. Mở Issue khi gặp lỗi: vào tab Issues → New issue. Có template sẵn cho bug report và feature request.
4. Đóng góp code: nhánh main là "production". Bạn tạo nhánh riêng (VD: git checkout -b fix/typo) → sửa → push → mở Pull Request. CI sẽ tự chạy test.
5. Cài Git desktop client (tùy chọn): desktop.github.com — dùng GUI thay vì dòng lệnh.

📚 Tài liệu GitHub chính thức (tiếng Việt có một số)

• docs.github.com/get-started — Quickstart cho người mới.
• docs.github.com/actions — Tự động hóa CI/CD với GitHub Actions.
• docs.github.com/pages — Host web tĩnh miễn phí.
• docs.github.com/releases — Tạo Release kèm file đính kèm (wheel .whl).

Mẹo: bạn có thể Watch repo (nút 👁 ở góc phải trên) → chọn All activity để nhận email mỗi khi có Release mới hoặc Issue quan trọng.