Synapse

Frappe 및 ERPNext를 위한 권한 인식 MCP 서버입니다. LLM 클라이언트가 사이트의 데이터를 실제 사용자로, 해당 사용자의 권한 하에 OAuth를 통해 읽고 쓸 수 있게 하며, 모든 호출은 감사 로그에 기록됩니다.

POST https://<your-site>/api/method/synapse.mcp.handle_mcp

왜 또 하나인가

대부분의 Frappe MCP 서버는 권한 상승 상태로 실행되며 모델에 원시 SQL 또는 ignore_permissions 문서 접근을 허용합니다. 개인 샌드박스에서는 괜찮지만 비즈니스 시스템에서는 용납할 수 없습니다. Synapse는 정반대의 입장을 취합니다:

• 어디에도 ignore_permissions가 없습니다. 모든 도구는 호출한 사용자로 실행됩니다. DocType 권한, 사용자 권한, 공유 규칙, 제출/취소 권한이 모두 적용되며, 쓰기는 Document.insert/save/submit/cancel을 통해 이루어지므로 검증, 훅, 워크플로우가 데스크에서와 똑같이 실행됩니다.

• 권한 위에 두 번째 경계선이 있습니다. "이 사용자는 데스크에서 판매 송장을 편집할 수 있다"와 "이 사용자의 토큰을 보유한 에이전트가 판매 송장을 편집할 수 있다"는 서로 다른 결정이기 때문입니다.

• 모든 것이 기록됩니다. 도구에 도달하기 전에 거부된 호출도 포함됩니다.

• 의존성이 없습니다. MCP 서버가 번들로 제공되므로 bench install-app이 설치의 전부이며 bench update도 안전합니다.

Related MCP server: Frappe Assistant Core

설치

bench get-app https://github.com/erpuae/synapse
bench --site <your-site> install-app synapse

그런 다음 언제든지 사이트 상태를 확인하세요:

bench --site <your-site> execute synapse.mcp_tools.check.report

구성된 내용과 누락된 내용을 수정해야 할 순서대로 출력합니다. 새로 설치하면 완전히 닫혀 있습니다. 직접 지정하기 전까지는 아무것도 접근할 수 없습니다.

도구

날짜는 MCP 설정에 지정된 형식으로 반환되며 기본값은 ISO입니다. 쓰기는 ISO 또는 DD-MM-YYYY를 모두 허용하므로 읽기-수정-쓰기 왕복에서 일과 월이 바뀔 수 없습니다.

의도적으로 노출하지 않음: frappe.db.set_value(검증과 훅을 건너뜀 — set_value 도구는 대신 문서를 로드하고 저장함), 임의의 화이트리스트 메서드 실행, 이름 바꾸기 및 수정.

네 가지 게이트

모든 호출은 네 가지를 모두 통과합니다. 서로 독립적이며 가장 좁은 것이 우선합니다.

1. 인증. 엔드포인트가 게스트에게 닫혀 있으므로 인증되지 않은 POST는 도구 코드가 실행되기 전에 프레임워크에서 거부됩니다.

2. 도구에 대한 역할. 문서 도구에는 MCP Agent가, SQL 도구에는 MCP SQL Reader가 필요합니다. 역할이 없으면 도구가 나열조차 되지 않습니다.

3. MCP 액세스 목록(MCP 설정), 허용 목록 또는 차단 목록. 읽기 이외의 작업에는 호출자가 해당 작업에 대한 역할을 사이트에서 부여받아야 합니다.

4. Frappe 자체 권한은 위에서 설명한 대로입니다.

관리자도 예외가 아닙니다. 모든 역할을 보유하므로 게이트 2와 3의 역할 검사는 통과하지만 DocType 목록은 여전히 바인딩됩니다.

액세스 모드

허용 목록 — 나열된 DocType만 작업이 선택된 상태로 도달할 수 있습니다. 실패 시 닫힙니다. 새 DocType은 다른 지정이 있을 때까지 도달할 수 없습니다. 이것이 기본값이며, 새로 설치하면 목록이 비어 있으므로 아무것도 도달할 수 없습니다.

차단 목록 — 나열된 DocType을 제외한 모든 DocType에 도달할 수 있습니다. 사용자 자신의 Frappe 권한이 작업 경계가 되며, 목록은 어떤 에이전트도 건드리지 말아야 할 것을 잘라냅니다. 각 행은 기본적으로 모든 것을 차단합니다. 읽기 차단을 해제하면 DocType을 읽기 전용으로 둘 수 있습니다.

차단 목록은 전체 ERP에서 사용하기 더 쉽습니다. 대가로 새 DocType이 도달 가능한 상태로 도착하므로 해당 모드에서는 나열 여부와 관계없이 두 세트가 적용됩니다.

• 도달 불가: OAuth Bearer Token, OAuth Authorization Code, OAuth Client, Token Cache, Social Login Key, Connected App, Webhook, Email Account, Integration Request, User Social Login, Access Log. 이것들을 읽는 것은 독자가 작성자가 되는 방법입니다.

• 항상 읽기 전용: DocType, DocField, DocPerm, Custom DocPerm, Custom Field, Property Setter, Server Script, Client Script, Print Format, Report, Role, Has Role, User, User Permission, System Settings, Workflow, Scheduled Job Type. Custom DocPerm을 편집할 수 있는 에이전트는 스스로에게 무엇이든 부여할 수 있습니다.

허용 목록 모드에서는 두 세트 모두 적용되지 않습니다. 테이블만이 유일한 권한입니다.

하위 테이블은 직접 도달할 수 없습니다. 상위 테이블을 통해 읽고 씁니다. 일치는 대소문자를 구분하지 않으며 DocType 이름은 목록을 참조하기 전에 사이트에 대해 정규화되므로 salary slip이 Salary Slip 행을 우회할 수 없습니다.

수백 개의 그리드 행을 선택하지 않고 큰 허용 목록을 채우려면:

bench --site <your-site> execute synapse.mcp_tools.allowlist.grant_all --kwargs "{'dry_run': 1}"
bench --site <your-site> execute synapse.mcp_tools.allowlist.grant_all
bench --site <your-site> execute synapse.mcp_tools.allowlist.show

grant_all은 기본적으로 읽기 전용이며 동일한 두 개의 보호된 세트를 적용합니다. 모든 것을 도달 가능하게 하려면 빈 목록이 있는 차단 목록 모드가 700개의 허용 목록 행보다 더 정직합니다.

설정

1. OAuth. Frappe 16은 OAuth 서버 메타데이터를 게시하고 동적 클라이언트 등록을 지원하므로 OAuth 클라이언트 레코드를 수동으로 만들지 않고도 MCP 클라이언트가 연결할 수 있습니다. 기본적으로 꺼져 있습니다. OAuth 설정에서 인증 서버 메타데이터 표시, 보호 리소스 메타데이터 표시, 동적 클라이언트 등록 활성화를 켜세요. Synapse는 이를 변경하지 않습니다. 사이트 전체의 OAuth 동작에 영향을 미치기 때문입니다.

토큰이 부여하는 것이 무엇인지 명확히 하세요. Frappe OAuth 토큰은 MCP로 범위가 지정되지 않습니다. 해당 사용자로 전체 /api 표면을 승인합니다.

2. 에이전트가 작동할 사용자에게 MCP Agent를 할당하세요. 인증하는 사람이 모든 도구가 실행되는 ID이므로 관리자 대신 에이전트가 보아야 하는 것으로 사용자 범위를 지정하세요.

3. MCP 설정을 작성하세요. MCP 엔드포인트 활성화를 선택하고 액세스 모드를 선택한 다음 표시되는 목록을 작성하세요. 이 시점에서 읽기가 작동합니다. 쓰기의 경우 쓰기 도구 활성화도 선택하고 역할 권한에서 특정 역할에 작업을 부여하세요. 해당 테이블이 비어 있으면 다른 설정과 관계없이 엔드포인트는 읽기 전용으로 유지됩니다.

클라이언트 연결

claude mcp add --transport http mysite https://<your-site>/api/method/synapse.mcp.handle_mcp

그런 다음 인증하세요. 브라우저가 사이트의 로그인 페이지에서 열립니다. OAuth와 함께 Streamable HTTP를 사용하는 모든 MCP 클라이언트는 동일한 방식으로 작동합니다. Claude Desktop에서는 설정 → 커넥터 → 사용자 지정 커넥터 추가에서 동일한 URL로 연결합니다.

원시 SQL — 활성화하기 전에 읽어보세요

run_sql_query는 Frappe의 권한 시스템을 완전히 우회합니다. MCP SQL Reader 역할을 보유한 사용자는 DocType 권한에 관계없이 사이트의 모든 테이블을 읽을 수 있습니다. 이미 전체 데이터베이스 액세스 권한이 있는 사용자에게만 부여하세요.

읽기 전용 SQL 도구 활성화를 선택할 때까지 꺼져 있으며 DocType 액세스 목록을 사용하지 않습니다. DocType 이름을 지정하지 않기 때문입니다. get_list 및 get_doc을 선호하세요. 표현할 수 없는 조인 또는 집계에만 SQL을 사용하세요. 에이전트가 지속적으로 SQL을 사용한다면 문서 도구에 필요한 것이 빠져 있는 것입니다.

뒤에는 두 개의 레이어가 있습니다.

1. 읽기 전용 데이터베이스 사용자는 MariaDB로 적용되므로 텍스트 필터를 통과하는 쿼리도 쓸 수 없습니다.

2. mcp_tools/guard.py — 명령문 유형, 주석 없음, 스택 명령문 없음, 키워드 블랙리스트, 테이블 블랙리스트 및 길이 제한. 텍스트 일치이므로 보조적인 안전장치로 취급하세요.

사이트별로 레이어 1을 설정하세요. MariaDB 루트로:

CREATE USER 'mcp_ro'@'localhost' IDENTIFIED BY '<STRONG_PASSWORD>';
GRANT SELECT ON `<DB_NAME>`.* TO 'mcp_ro'@'localhost';
REVOKE FILE ON *.* FROM 'mcp_ro'@'localhost';
FLUSH PRIVILEGES;

그런 다음 site_config.json에서(리포지토리에는 절대 안 됨):

{
  "mcp_ro_db_user": "mcp_ro",
  "mcp_ro_db_password": "<STRONG_PASSWORD>"
}

해당 키가 없으면 도구는 사이트 자체의 읽기-쓰기 연결로 대체되어 모든 쿼리 후에 롤백됩니다. 작동하지만 가드가 유일한 경계가 됩니다. 두 번째 데이터베이스 사용자가 불가능한 호스팅 플랫폼에서는 해당 대체가 유일한 옵션입니다. SQL을 활성화하기 전에 의식적으로 결정하세요.

site_config.json의 mcp_sql_blocked_tables로 사이트별 테이블 블록리스트를 확장하세요. MariaDB 전용입니다. connection.py는 다른 백엔드에서 NotImplementedError를 발생시킵니다.

감사

모든 호출은 MCP 액세스 로그 행(성공, 거부 또는 오류)을 도구, 사용자, 인증 방법, IP, 터치된 문서, 행 수 및 타이밍과 함께 기록합니다. 쓰기는 제출된 값과 변경된 각 필드의 전후도 기록합니다. 도구 본문이 실행되기 전에 거부된 호출(알 수 없는 도구, 역할 누락, 맞지 않는 인수)도 기록됩니다. 권한이 없는 도구를 탐색하는 에이전트는 정확히 감사 추적을 위한 것입니다.

로그에 완전히 없는 호출은 서버에 도달하지 않은 것입니다. 도구가 차단된 것처럼 보이고 로그에 아무것도 없으면 차단은 클라이언트, 가장 자주 자체 도구 권한 프롬프트에 있는 것입니다. 가장 먼저 확인해야 할 사항입니다.

행은 롤백 후 자체 커밋으로 기록되므로 실패하거나 거부된 쓰기도 기록을 남깁니다. 시스템 관리자가 읽고 보고할 수 있으며 데스크에서 만들거나 편집할 수 없습니다. reference_doctype 및 reference_name은 의도적으로 링크 필드가 아닌 데이터 필드입니다. 감사 행은 기록하는 항목의 삭제를 차단해서는 안 됩니다. 일일 작업은 보존 기간이 지난 행을 삭제합니다. 데이터 자체를 로그에 복제하지 않아야 하는 경우 필드 값 기록을 선택 취소하세요. 암호와 유사한 필드는 어느 쪽이든 마스킹됩니다.

테스트

bench --site <your-site> run-tests --app synapse

액세스 목록, SQL 가드, 도구 스키마 및 값 변환은 frappe에서 아무것도 가져오지 않으므로 사이트 없이도 실행됩니다:

python -m unittest discover -s apps/synapse -p 'test_mcp_*.py'

라이선스

GNU Affero General Public License v3.0 이상. LICENSE를 참조하세요.

AGPL은 의도적입니다. 수정된 Synapse를 네트워크 서비스로 실행하는 경우 이를 사용하는 사람들은 귀하의 변경 사항을 받을 자격이 있습니다.