secureFlows MCP 서버

클라우드에 배포 가능한 MCP 서버로, secureFlows OpenAPI 표면 중 ai-safe 및 ai-optional 태그가 붙은 부분을 래핑합니다.

이 저장소는 공개 미러로, 실제 개발이 이루어지는 비공개 secureFlows 모노레포에서 주기적으로 게시됩니다. 이슈와 PR은 환영합니다. 큰 변경 사항은 먼저 업스트림에 반영되기까지 릴리스 주기가 걸릴 수 있습니다.

MCP 서버란 무엇인가요?

MCP 서버는 AI 클라이언트가 표준 방식으로 호출할 수 있는 "도구" 집합을 노출하는 작은 HTTP 서비스입니다.

이 저장소에서:

• secureFlows MCP 서버는 OpenAPI YAML 스펙에서 자동 생성된 도구들을 노출합니다.

• 클라이언트가 도구를 호출하면 MCP 서버는 호출을 실제 secureFlows 백엔드(connection.host)로 전달하고 응답을 정규화된 도구 결과로 반환합니다.

이를 통해 AI 클라이언트는:

• listTools를 통해 사용 가능한 secureFlows 작업을 발견하고

• callTool을 통해 호출할 수 있습니다.

• API 표면을 하드코딩하거나 수동으로 인증/헤더를 연결할 필요 없이 말이죠.

기능

두 종류의 도구가 src/server.ts에 함께 등록됩니다:

생성된 도구 (src/tools/build-tools.ts) — OpenAPI 작업당 하나:

• 다음을 로드합니다:

  • docs/openapi/session/secure-flows-session-api.yaml

  • docs/openapi/user/secure-flows-user-api.yaml

  • docs/openapi/docs/secure-flows-docs-api.yaml

• ai-safe 또는 ai-optional 태그가 붙은 작업만 MCP 도구로 노출합니다.

• 호출자가 제공한 secureFlows 호스트로 요청을 전달합니다 — secureFlows 특정 판단이 없는 얇은 일반 HTTP 래퍼입니다. 이 모든 도구는 활성 auth.* 토큰이 필요하므로 세션이 이미 존재할 때만 유용합니다 (아래 런타임 모델 참조).

• MCP 도구 입력에서 secureFlows 인증 헤더를 매핑합니다:

  • auth.firebaseToken

  • auth.sessionToken

  • auth.userToken

정적 도구 (src/tools/static-tools.ts) — 스펙에서 생성되지 않은 수작업 도구:

• secureflows_build_login_url / secureflows_build_logout_url — 호스팅 로그인 및 리다이렉트 로그아웃 URL을 구조적으로 올바르게 생성합니다 (항상 /app/sessions/login, 레거시 /app/login이 아님; 로그아웃 후 redirect_uri가 /callback을 가리키거나 session_token을 노출하는 것을 거부). secureFlows 토큰이 필요 없습니다.

• secureflows_lint_integration — 생성된 앱 소스를 통합 규칙에 대해 검사하고, 에이전트가 스스로 규율을 지켜야 하는 산문 대신 구조화된 결과를 보고합니다. secureFlows 토큰이 필요 없습니다. 두 종류의 결과가 있습니다:

  • scope: "file" — 금지된 구성이 정확한 file:line에 존재합니다: 환경 변수 구성 상수, localStorage의 토큰, 레거시 /app/login, fetch/XHR 로그아웃, 클라이언트 측 JWT 디코딩, 로그아웃 시 해지, 빈 catch {}, 비인증 오류 시 setSession(null) 복원, session === null에 게이트된 Continue CTA, …

  • scope: "project" — 전달된 모든 파일에 걸쳐 필요한 처리가 부재합니다: 401/410 감지하지만 토큰을 지우지 않음, 403을 처리하지 않음, 또는 BILLING_GRACE_LOCK 예외 없이 403 처리.

  부재 검사가 존재하는 이유는 패턴 규칙이 구조적으로 실제 생성된 앱을 지배하는 결함 클래스를 잡을 수 없기 때문입니다. 측정 결과: 평가 하네스의 LLM 판정자가 4/10을 준 실제 평가판 앱에서 — "로그아웃 시 토큰이 지워지지 않음", "403 변형 미처리", "오류 처리 없음"을 인용 — 패턴 규칙만으로는 0개의 결과를 생성했습니다. 왜냐하면 그 버그들은 모두 부재이며, 정규식은 존재하는 것만 볼 수 있기 때문입니다. 부재 검사를 포함하면 3개를 생성하며, error 심각도의 토큰 정리 항목도 포함됩니다. 두 검사 종류 모두 표준 templates/web-app-secureflows 스타터에 대해 검증되며, 이 스타터는 결과가 0이어야 합니다.

  여전히 휴리스틱 텍스트 분석이며 파서나 타입 체커가 아닙니다: 규칙이 없는 것은 놓치고, 프로젝트 검사는 잘못된 위치의 올바른 키워드로 충족될 수 있으며, 실행 중인 앱이 필요한 검사(인증 가드 마운트 경쟁, 새로고침 검사)는 다룰 수 없습니다. 빠른 첫 패스 — SKILL.md의 Agent 구현 체크리스트를 대체하지 않습니다.

이 정적 도구들이 존재하는 이유는 생성된 도구가 세션이 존재하기 전에 발생하는 통합 부분 — 리다이렉트/콜백/토큰 수명 주기 코드 스캐폴딩 — 을 도울 수 없기 때문이며, 이는 대부분의 secureFlows 통합 실수가 발생하는 지점입니다.

상태 비저장 HTTP MCP 전송을 사용하므로 서버는 테넌트 구성이나 비밀을 영속화하지 않습니다.

런타임 모델

각 도구 호출은 다음을 받습니다:

• connection.host: secureFlows 기본 URL

• connection.workspaceName: 선택적 기본 작업 공간

• connection.appId: 선택적 기본 애플리케이션 ID

• auth.*: 선택한 엔드포인트가 필요로 하는 토큰

workspaceName과 appId는 안정적인 앱 구성으로 취급됩니다. 서버는 호출자가 생략한 경우 이를 알려진 secureFlows 요청 형태에 주입합니다.

에이전트용 (유일하게 지원되는 클라이언트 경로)

MCP 클라이언트를 호스팅된 URL로 지정하세요 — 제품과 동일한 호스트, 경로 /mcp (서브도메인이 아님):

{
  "mcpServers": {
    "secureflows": {
      "url": "https://www.secure-flows.com/mcp"
    }
  }
}

에이전트에게 npx를 실행하거나 localhost를 사용하라고 말하지 마세요 — 이는 이야기를 분열시키고 로컬 프로세스를 시작하지 않는 모든 사람을 망가뜨립니다. 웹 Docker 이미지에 연결되어 있습니다 (Node는 127.0.0.1:8787, nginx location = /mcp; docs/ROUTING.md 참조). Node 프로세스는 uncaughtException / unhandledRejection 가드를 설치하여 단일 잘못된 요청이 프로세스를 종료하지 않도록 합니다. docker/entrypoint.sh는 프로세스가 여전히 종료되면 MCP를 다시 시작합니다.

로컬 개발 (이 패키지의 유지 관리자)

cd mcp-server
npm install
npm run build
npm test
npm run dev

서버는 기본적으로 http://0.0.0.0:8787에서 시작합니다 (POST /mcp, GET /health). 이는 MCP 서버 자체를 변경하기 위한 것이며, 제품 에이전트가 구성해야 하는 경로가 아닙니다.

환경 변수

• PORT: HTTP 포트, 기본값 8787 (웹 컨테이너에서 entrypoint는 MCP 자식 프로세스에만 PORT=8787을 설정하여 nginx가 Render의 공개 $PORT를 유지하도록 함)

• HOST: 바인드 호스트, 기본값 0.0.0.0 (웹 컨테이너는 127.0.0.1 사용)

• ALLOWED_HOSTS: MCP 호스트 헤더 검증을 위한 선택적 쉼표로 구분된 호스트 허용 목록

• MCP_ALLOWED_HOSTS: 이미지 내 프로세스 시작 시 ALLOWED_HOSTS에 대한 entrypoint 재정의

엔드포인트

• POST /mcp: MCP Streamable HTTP 엔드포인트

• GET /health: 상태 확인 (nginx를 통해 공개적으로 GET /mcp/health로 노출)

애플리케이션에 secureFlows 포함

제품 앱은 이 서버를 통하지 않고 직접 secureFlows HTTP API 및 호스팅 로그인과 통합합니다. 다음에서 시작하세요:

• docs/integration/quickstart.md — 프로비저닝 (작업 공간 + 애플리케이션) 및 런타임 호스팅 로그인

• docs/integration/CONCEPT.md — 기본 순서: 고급 기능 전에 로그인 → 작업 공간 생성

• docs/openapi/integration-auth.yaml — /app/sessions/login (세션 앱) vs /app/login (레거시/콘솔)

제품 앱은 여전히 위의 HTTP API와 직접 통합하며, 이 서버를 통하지 않습니다. 여기의 생성된 도구는 이미 토큰이 있는 에이전트/자동화를 위한 것입니다 (테스트, 스크립트 검증). 정적 도구 (secureflows_build_login_url, secureflows_build_logout_url, secureflows_lint_integration)는 토큰이 필요 없으며, 코딩 에이전트가 통합을 스캐폴딩하는 동안 호출하도록 설계되었습니다 — 위의 기능 섹션을 참조하세요.

이 MCP 서버 테스트

1. mcp-server/에서 npm test — 단위 테스트 및 HTTP 스모크 (test/http-smoke.test.ts): 임시 포트에서 Express 앱을 시작하고 GET /health, GET /mcp → 405, 실제 Streamable-HTTP 클라이언트 listTools + callTool(secureflows_build_login_url)을 확인합니다.

2. 배포 후: Playwright tests/smoke/mcp-health.spec.ts가 대상 호스트의 공개 GET /mcp/health 및 GET /mcp를 확인합니다 (프로덕션 스모크 작업).

3. 로컬 유지 관리자 루프: npm run dev, 그 다음 curl -sS http://127.0.0.1:8787/health.

4. 선택 사항: 생성된 도구에 대해 connection.host + auth.*를 사용하여 POST /mcp에 대한 MCP 클라이언트.

배포

웹 Docker 이미지에 포함되어 www.secure-flows.com / 스테이징의 /mcp에서 프록시됩니다 (위의 에이전트용 참조). 별도의 서브도메인은 없습니다.

npm 패키지 secureflows-mcp-server는 CI가 버전이 지정된 아티팩트를 게시하는 방법입니다 (그리고 mcp-server/Dockerfile에서 독립형 컨테이너를 빌드할 수 있는 방법). 에이전트가 사용하는 설정 경로는 아닙니다. v*.*.* 태그에서 .github/workflows/publish-secureflows-mcp-server.yml을 통해 게시합니다.

docker build -f mcp-server/Dockerfile -t secureflows-mcp-server .
docker run --rm -p 8787:8787 secureflows-mcp-server

참고 사항

• 호스팅 로그인 / 리다이렉트 엔드포인트는 OpenAPI 스펙에서 ai-safe 또는 ai-optional 태그가 붙은 경우에만 노출됩니다.

• 문서 검색 (get_docs_search)은 ai-safe이며 auth.*가 필요 없습니다 — connection.host와 쿼리 q만 필요합니다.

• 인간 전용 관리자 콘솔 API는 의도적으로 제외됩니다.

• 각 도구의 응답 페이로드에는 다음이 포함됩니다:

  • status

  • ok

  • url

  • headers

  • data