@expertcustom/funilaria-mcp

Aurora の AI が Funilaria & Pintura ポータルへの書き込みと読み取りに使用する、型付きツールを備えた MCP（Model Context Protocol）サーバーです。

mcp-fetch を置き換え、システムプロンプトに書かれたシークレットを使って 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 の代わりにシークレットを受け入れ、ShopContextGuard は shopId を必須にします。存在しない ID に対しては 404 Oficina não encontrada を返し、「ショップに在庫がない」と誤解される空のリストは返しません。

ユーザーセッション（POST /auth/entrar の JWT）は、ローカル開発向けに引き続きサポートされています。shopId がない場合、ショップはセッションから取得されます。アクセストークンは約15分で失効するため、クライアントはリフレッシュトークンで自動更新し、ローテーション後のペアを書き直します。このモードで shopId を渡すと、理由とともに即座に拒否されます。このルートは、要求されたショップであるかのようにセッションのショップを返すことになるためです。

設定 — env が主経路

本番では、このプロセスを起動するのは Aurora のランタイムで、環境変数を注入します。端末は存在せず、ログインコマンドも実行されません。このサーバーはディスクが完全に空の状態でも動作します。

このエイリアスを用意しているのは、バックエンドの .env をコピーした際に、プレフィックスが異なるためにシークレットが「消えたように見える」というよくあるミスへの対策です。AURORA_WEBHOOK_SECRET は両側でまったく同じ値です。

シークレットはハードコードも、プロンプトからの読み取りもされません。~/.config/funilaria-mcp/credentials.json（モード 0600）はローカル開発のための便宜です。env が常に優先され、env の値がディスクに書き込まれることはありません。

起動時に、サーバーは stderr（stdout は MCP プロトコル専用）に、何が設定されているか、各設定がどの 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 の登録情報そのものに変数を設定してサーバーを登録します — ログインもシステムプロンプトへのシークレット記載もありません。

{
  "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

バックエンドの未解決事項

当初の4件（到達不能な在庫 Webhook、サービスの資格情報なしでの読み取り、検証後にチェックされていた始末、デッドコードとしての距離）は、バックエンドで修正済みであり、localhost:3334 に対して再検証済みです。残っているのは次のとおりです。

1. Aurora の AI には shopId を見つける手段がありません。 それは AI が暗記する必要がある唯一の情報です。現在は FUNILARIA_SHOP_ID 経由でしか取得できず、そのせいで1サーバーが1ショップに固定されてしまい、サービス設計の動機となったマルチショップのケースが壊れています。

   最も解決コストが低いのは lancar_consumo です。バックエンドは WhatsApp 番号から従業員とショップをすでに特定しています が、返すのは確認用テキストだけです。IntakeResult が shopId と memberId を含んでいれば、「ニスを100ml使った」→「今月はいくら使った？」という会話が成立し、両方の ID を持って consultar_balancete を呼べます。それがなければ、2つ目の質問にはどうしても答えられません。

2. GET /estoque/movimentos が @AllowService() の対象外のままです。 ListMovementsDto には shopId が宣言されていますが、そのルートはサービスの資格情報を受け付けないため、このパラメータは使えないままです。このルートに認証を付けるか、あるいは存在しない機能を示唆しないように DTO からフィールドを削除すべきです。

3. HMAC 署名はまだ検証されていません。 署名シークレットがある場合、クライアントはすでに x-timestamp と x-signature を送信しています（上記参照）。ADR-001 が想定する、リプレイとログ漏えいを防ぐサーバー側の検証がまだ必要です。

開発

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