Frasma

Smithery の Frasma

これは、create-next-app で初期化された Next.js プロジェクトです。

はじめに

まず、開発サーバーを起動します。

npm run dev
# or
yarn dev

ブラウザーで http://localhost:3000 を開くと、結果を確認できます。

pages/index.tsx を変更すると、ページを編集できます。ファイルを編集すると、ページは自動的に更新されます。

pages/api ディレクトリは /api/* にマッピングされています。このディレクトリ内のファイルは、React ページではなく API ルートとして扱われます。

プロセス概要（見積もり依頼）

ランディングフォームとチャットウィジェットは、どちらも プロセス概要 を POST /api/request-process-assessment に送信します。Francesco はこの概要を使って見積もりを作成します。

項目：名前、仕事用メールアドレス、任意の会社名と役職、必須のプロセス、任意の現在使用中のツールと処理量。

MONGODB_URI が設定されている場合、同じエンドポイントで users をアップサートし、leads を挿入して、project_brief_submitted を記録します。

必須の環境変数

プロジェクトのルートに .env.local ファイルを作成し、次の内容を記述します。

# Destination email (defaults to [email protected])
[email protected]

# Sender identity (defaults to SMTP_USER if using SMTP)
[email protected]

# Sender display name (defaults to "Frasma")
MEETING_FROM_NAME=Frasma

# --- Option A (recommended): Gmail SMTP via App Password ---
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
[email protected]
SMTP_PASS=your_gmail_app_password

# --- Option B: Resend ---
# RESEND_API_KEY=your_resend_api_key

# Notion: inbound leads go to ricerca_clienti (Frasma view)
# NOTION_TOKEN=ntn_your_integration_token
# NOTION_LEADS_DATABASE_ID=32e90196-c414-80b3-9a53-c00ffe4019c9

# OpenAI Ads Measurement Pixel (ChatGPT Ads conversions). Public, inlined at build
# time: set it in Vercel before the deploy that should carry the pixel.
# NEXT_PUBLIC_OAI_PIXEL_ID=your_pixel_id

注意：

• 本番環境では、これらの変数をホスティングプロバイダー（例：Vercel）に設定してください。
• SMTP も Resend も設定されていない場合、API はエラーを返し、ポップアップにそのエラーが表示されます。

診断チャットエージェント

ウェブサイトのチャットは、プロセス診断アシスタントです。lib/knowledge/ にある、バージョン管理されたバイリンガルのナレッジベースを使用して、次のことを行います。

• 業務上のボトルネックを特定する。
• ワークフロー、システム、処理量、ベースライン指標、データ、制約を収集する。
• ニーズを Frasma の機能に対応付ける。
• 編集可能なプロセス概要を作成する。
• ユーザーが明示的に確認した後にのみ、その概要を POST /api/request-process-assessment に送信する。

アシスタントがタイムアウトした場合、ウィジェットには会話履歴をもとに事前入力された同じプロセス概要フォームが表示されます（追加の LLM 呼び出しはありません）。

各ブラウザーセッションでは、localStorage に conversationId が保存されます。メッセージは、MongoDB Atlas に公式の Node.js ドライバーを介してサーバー側で永続化されます。ウィジェットを再度開くと、GET /api/conversations/:id を使って会話が復元されます。MongoDB が設定されていない場合、チャットはステートレスモードで動作します。

ナレッジベースや診断例には、価格、保証された節約額、顧客の秘密情報、認証情報、または第三者の個人データを追加しないでください。

必須の OpenAI 環境変数（チャットエージェント＋プロセス評価フォームの音声入力）：

OPENAI_API_KEY=your_openai_api_key

# Optional; defaults to gpt-4o-mini
OPENAI_CHAT_MODEL=gpt-4o-mini

# Optional; defaults to whisper-1 (process assessment voice dictation)
OPENAI_WHISPER_MODEL=whisper-1

チャットの永続化（MongoDB Atlas）

永続化は任意ですが、本番環境では推奨されます。設定すると、API は以下を保存します。

• 会話メタデータ（lang、timezone、pagePath、コンバージョンフラグ）；
• ユーザーとアシスタントのメッセージ；
• プロセス概要からのコンバージョンイベント（project_brief_submitted）。

セットアップ：

1. MongoDB Atlas で無料の M0 クラスターを作成します（推奨リージョン：フランクフルトまたはアイルランド）。
2. 読み取り／書き込みアクセス権を持つデータベースユーザーを作成します。
3. Network Access で 0.0.0.0/0 を許可します（Vercel のサーバーレス実行に必要です）。
4. 接続文字列をコピーし、ローカル環境と Vercel で以下の環境変数を設定します。

MONGODB_URI=mongodb+srv://user:[email protected]/frasma_chat?retryWrites=true&w=majority
# Optional. Days from the last contact; defaults to 730 and is capped at 730
# (24 months), the retention promised by the privacy policy.
CHAT_RETENTION_DAYS=730

conversations、messages、events、leads、users に対するインデックスと expiresAt の TTL ポリシーは、初回使用時に自動作成されます。登録、メッセージ、プロセス概要など、連絡があるたびに会話と訪問者が所有するすべてのデータの期限が延長されるため、最後の連絡から CHAT_RETENTION_DAYS 日後にデータが期限切れになります。

このポリシーより前に作成されたデータベースには expiresAt のないドキュメントがあり、TTL インデックスでは削除されません。一度だけバックフィルしてください（冪等です。--dry-run は件数のみを出力します）。

node scripts/backfill-retention.mjs --dry-run
npm run backfill:retention

MONGODB_URI が設定されていなくても、POST /api/chat とフォーム API は引き続き動作します。永続化の呼び出しは通知なしでスキップされます。

接続を確認します。

npm run check:mongodb
curl http://localhost:3000/api/status

正しく設定されている場合の期待値：

{
  "persistence": { "configured": true, "connected": true }
}

チャットへの応答が成功すると、conversationId も含まれます。

MongoDB のトラブルシューティング

1. Vercel のサーバーレス実行には、Atlas の Network Access で 0.0.0.0/0 を許可する必要があります。
2. URI にはデータベース名を含める必要があります：...mongodb.net/frasma_chat?...
3. Atlas ユーザーのパスワードをリセットした場合は、.env.local と Vercel の両方を更新してから再デプロイします。
4. パスワードに含まれる特殊文字（@、#、% など）は URL エンコードしてください。
5. Vercel の環境変数を変更した後は、新しいデプロイを実行してください。環境変数の変更は既存のデプロイに自動適用されません。

AI ディスカバリーと公開 MCP

エージェントと人間向けの公開ディスカバリー情報：

リソース	URL
エージェントハブ	https://www.frasma.org/for-agents
サービスハブ	https://www.frasma.org/servizi
事例	https://www.frasma.org/casi
llms.txt	https://www.frasma.org/llms.txt
llms-it.txt	https://www.frasma.org/llms-it.txt
ホームの Markdown	Accept: text/markdown を指定した GET /
OpenAPI	https://www.frasma.org/openapi.json
API カタログ	https://www.frasma.org/.well-known/api-catalog
エージェントスキル	https://www.frasma.org/.well-known/agent-skills/index.json
MCP（Streamable HTTP）	https://www.frasma.org/api/mcp

MCP ツール（読み取り専用＋引き継ぎ）

• get_frasma_profile
• search_frasma_knowledge
• get_diagnostic_framework
• prepare_diagnostic_summary — 診断を検証し、引き継ぎ URL を返します。メールは送信しません
• prepare_project_brief — 見積もりに使用するプロセス概要を検証します。メールは送信しません

Cursor / Claude Desktop のリモート設定例：

{
  "mcpServers": {
    "frasma": {
      "url": "https://www.frasma.org/api/mcp"
    }
  }
}

stdio のみを使用するクライアントの場合：

{
  "mcpServers": {
    "frasma": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.frasma.org/api/mcp"]
    }
  }
}

ディレクトリへの掲載（本番デプロイ後）

1. 本番環境で /for-agents、/servizi、/llms.txt、/llms-it.txt、/api/mcp が応答することを確認します。
2. スモークテスト：curl -H 'Accept: text/markdown' -H 'Accept-Language: it' https://www.frasma.org/servizi/ddt-erp（イタリア語の DDT/Mago のコピー）、さらに /api/mcp に対して MCP の initialize と tools/list を実行します。
3. /for-agents に記載された短い説明（サービスハブに言及）を使って、関連する MCP ディレクトリにサーバーを登録します。
4. SKILL.md の変更時は、エージェントスキルのダイジェストを同期してください（shasum -a 256）。

品質チェック：

npm run lint
npm test
npm run build

詳細情報

Next.js の詳細については、以下のリソースをご覧ください。

• Next.js ドキュメント — Next.js の機能と API について学べます。
• Next.js を学ぶ — 対話形式の Next.js チュートリアルです。

Next.js の GitHub リポジトリもご覧ください。フィードバックや貢献を歓迎します。

Vercel にデプロイする

Next.js アプリをデプロイする最も簡単な方法は、Next.js の開発元が提供する Vercel Platform を利用することです。

詳しくは、Next.js のデプロイに関するドキュメントをご覧ください。