@expertcustom/funilaria-mcp

MCP(Model Context Protocol) 서버로, Aurora의 AI가 Funilaria & Pintura 포털에 쓰고 읽을 때 사용하는 타입이 지정된 도구를 포함합니다.

mcp-fetch를 대체하며, system prompt에 적힌 코드 자체를 사용해 HTTP 요청을 직접 구성합니다. 여기서는 각 작업이 스키마, 설명, 포르투갈어 오류를 갖춘 하나의 도구입니다.

IA do Aurora ──stdio──> npx @expertcustom/funilaria-mcp ──HTTPS──> backend NestJS

ADR-001에 따라 이 패키지는 어댑터입니다. 비즈니스 규칙은 여기에 없습니다. 모든 도구는 이미 존재하는 엔드포인트를 호출하며, 결정권은 계속 백엔드 서비스에 있습니다.

도구

인증

명시적 shopId가 있는 서비스 자격 증명이 쓰기와 읽기 모두의 기본 경로입니다. x-aurora-secret 헤더는 백엔드의 AURORA_WEBHOOK_SECRET과 같은 값입니다. 이 헤더는 사람을 나타내는 것이 아니라 서비스를 나타냅니다.

여러 공간을 담당하는 AI는 세션이 없으므로, 공간은 파라미터이지 암묵적 컨텍스트가 아닙니다. 백엔드의 재고 조회 라우트에서 이는 @AllowService()로 구현됩니다. JwtAuthGuard는 JWT 대신 이 secret 시크릿을 허용하고, ShopContextGuard는 shopId를 요구하게 됩니다. 존재하지 않는 id는 목록이 아닌 404 Oficina não encontrada를 반환하거나, "공간에 재고가 없다"는 착각을 부르는 빈 목록을 반환하지 않습니다.

사용자 세션(POST /auth/entrar의 JWT)은 로컬 개발 환경에서 계속 지원됩니다. shopId가 없으면 공간은 세션에서 가져옵니다. access token은 15분가량 유지되므로, 클라이언트가 refresh token으로 스스로 갱신하고 새로 로테이션된 쌍을 다시 저장합니다. 이 모드에서는 shopId를 전달하는 즉시 거부됩니다. 라우트가 요청된 것처럼 세션의 작업장을 대신 반환하게 되기 때문입니다.

설정 — env가 기본 경로

프로덕션에서 이 프로세스를 올리는 쪽은 Aurora 런타임이며 변수를 주입합니다. 터미널도 없고 로그인이 필요합니다. 서버는 디스크가 완전히 빈 채로도 동작합니다.

별칭이 존재하는 이유는 백엔드의 .env를 복사했는데 접두사가 달라서 시크릿이 "사라지는" 것으로 보이는 흔한 실수 때문입니다. AURORA_WEBHOOK_SECRET은 양쪽에서 똑같은 값입니다.

시크릿은 하드코딩되지 않거나 prompt에서 읽지 않습니다. ~/.config/funilaria-mcp/credentials.json 파일(모드 0600)은 로컬 개발 편의를 위한 것이고, env가 항상 우선하며 디스크에는 기록되지 않습니다.

시작 시 서버는 MCP 프로토콜이 stdout을 사용하므로 stderr에 현재 설정된 것과 각각 어느 env에서 왔는지를 한 줄로 씁니다. 값은 절대 쓰지 않습니다. 이는 변수 이름을 잘못 입력했을 때 Aurora 로그에 나타나는 내용입니다.

[funilaria-mcp] API: https://api.exemplo.com (FUNILARIA_API_URL) · Credencial de serviço: configurada via AURORA_WEBHOOK_SECRET · ...
[funilaria-mcp] Sem credencial de serviço: as tools de escrita vão recusar toda chamada. Defina FUNILARIA_SERVICE_SECRET no ambiente deste processo.

HMAC 서명

FUNILARIA_SIGNING_SECRET이 존재하면 모든 쓰기에는 다음도 포함됩니다.

x-timestamp: <epoch em segundos>
x-signature: sha256=<HMAC-SHA256(`${timestamp}.${corpo}`)>

이는 ADR-001에 기록된 개선입니다. 아직 서명을 검증하지 않습니다 — 알 수 없는 헤더는 무시되므로 서버 버전을 켜도 현재 실행 중인 것들을 망가지지 않습니다.

설치

Aurora AI 공간(프로덕션)

MCP 등록 정보에 변수들과 함께 직접 하는 것이 좋습니다. 로그인도 없고, system prompt에 시크릿도 없습니다.

{
  "command": "npx",
  "args": ["-y", "@expertcustom/funilaria-mcp"],
  "env": {
    "FUNILARIA_API_URL": "https://<api-do-portal>",
    "FUNILARIA_SERVICE_SECRET": "<mesmo valor de AURORA_WEBHOOK_SECRET>"
  }
}

로컬 개발 환경

# opção A — env no shell (igual à produção)
FUNILARIA_API_URL=http://localhost:3334 FUNILARIA_SERVICE_SECRET=... npx @expertcustom/funilaria-mcp

# opção B — guardar em ~/.config para não exportar em todo shell
npx @expertcustom/funilaria-mcp login-servico

# sessão de usuário: só é necessária para consultar_estoque sem shopId
npx @expertcustom/funilaria-mcp login

# conferir o que está valendo e de onde veio (nunca imprime segredo)
npx @expertcustom/funilaria-mcp status

# registrar no Claude Code
claude mcp add funilaria --env FUNILARIA_API_URL=http://localhost:3334 -- npx -y @expertcustom/funilaria-mcp

백엔드 잔여 작업

기존의 네 가지 잔여 작업(연결할 수 없는 재고 웹훅, 서비스 자격 없는 조회, 유효한 검증 후에 확인하던 시크릿, 데드 코드로 남아 있던 거리)은 백엔드에서 수정되었으며 localhost:3334를 대상으로 다시 잘못 검증되었습니다. 남은 사항은 다음과 같습니다.

1. AI가 shopId를 알아낼 수 없습니다. AI가 외워야 하는 유일한 값은 아니지만, 지금은 FUNILARIA_SHOP_ID로만 도달합니다. 이 때문에 서버 하나가 작업장 하나에 묶이고, 서비스 설계를 이끌었던 다중 작업장 사례가 무너집니다.

   가장 저비용으로 해결할 지점은 lancar_consumo입니다. 백엔드는 WhatsApp 번호로 직원과 작업장을 이미 파악하고 있지만, 확인 문구만 돌려줍니다. IntakeResult에 shopId와 memberId가 포함되 있다면 대화가 이어질 수 있습니다. "바니시 100ml 사용했지만" → "이번 달에 얼마나 썼지?"는 두 id를 손에 쥐고 consultar_balancete를 부르면 됩니다. 이게 없습니다면 두 번째 질문에는 답할 방법이 없습니다.

2. GET /estoque/movimentos는 @AllowService() 적용 범위에서 빠져 있었습니다. shopId는 ListMovementsDto에 선언되어 있지만, 라우트가 서비스 자격 증명을 받지 않아 해당 파라미터를 사용할 수 없습니다. 라우트를 표시하거나 DTO에서 필드를 빼서 존재하지 않는 기능을 함유하지 않아야 합니다.

3. HMAC 서명은 아직 검증되지 않습니다. 클라이언트는 서명 시크릿이 있을 때 이미 x-timestamp와 x-signature를 보냅니다(위 참고). ADR-101이 예상한 대로 replay와 로그 유출을 막기 위해 서버 쪽 검증이 필요합니다.

개발

npm install
npm run build     # tsc estrito, gera dist/
npm start         # sobe o servidor MCP em stdio