Frasma

[smithery badge]

Frasma on Smithery

This is a Next.js project bootstrapped with create-next-app.

Getting Started

First, run the development server:

npm run dev# oryarn dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying pages/index.tsx. The page auto-updates as you edit the file.

The pages/api directory is mapped to /api/*. Files in this directory are treated as API routes instead of React pages.

Process brief (quote request)

The landing form and the chat widget both submit a process brief to POST /api/request-process-assessment. Francesco uses that brief to prepare a quote.

Fields: name, work email, optional company and role, process (required), optional current tools and volume.

When MONGODB_URI is set, the same endpoint upserts users, inserts leads, and logs project_brief_submitted.

Required environment variables

Create a .env.local file in the project root with:

# 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.comSMTP_PORT=465SMTP_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

Notes:

• In production you should set these variables in your hosting provider (e.g. Vercel).
• If neither SMTP nor Resend is configured, the API returns an error and the popup shows it to the user.

Diagnostic chat agent

The website chat is a process-diagnostic assistant. It uses the bilingual, versioned knowledge base in lib/knowledge/ to:

• identify operational bottlenecks;
• collect workflow, systems, volumes, baseline metrics, data, and constraints;
• map the need to Frasma capabilities;
• prepare an editable process brief;
• submit that brief to POST /api/request-process-assessment only after explicit user review.

If the assistant times out, the widget shows the same process brief form, prefilled from the conversation history (no extra LLM call).

Each browser session stores a conversationId in localStorage. Messages are persisted server-side in MongoDB Atlas through the official Node.js driver. On reopen, the widget restores the conversation via GET /api/conversations/:id. If MongoDB is not configured, the chat keeps working in stateless mode.

Do not add prices, guaranteed savings, customer secrets, credentials, or personal data about third parties to the knowledge base or diagnostic examples.

Required OpenAI environment variable (chat agent + voice dictation on the process assessment form):

OPENAI_API_KEY=your_openai_api_key
# Optional; defaults to gpt-4o-miniOPENAI_CHAT_MODEL=gpt-4o-mini
# Optional; defaults to whisper-1 (process assessment voice dictation)OPENAI_WHISPER_MODEL=whisper-1

Chat persistence (MongoDB Atlas)

Persistence is optional but recommended in production. When configured, the API stores:

• conversation metadata (lang, timezone, pagePath, conversion flags);
• user and assistant messages;
• conversion events from the process brief (project_brief_submitted).

Setup:

1. Create a free M0 cluster on MongoDB Atlas (recommended region: Frankfurt or Ireland).
2. Create a database user with read/write access.
3. In Network Access, allow 0.0.0.0/0 (required for Vercel serverless).
4. Copy the connection string and set these environment variables locally and on 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

Indexes and a TTL policy on expiresAt are created automatically on first use for conversations, messages, events, leads and users. Every contact (registration, message, process brief) extends the deadline of the conversation and of everything the visitor owns, so data expires CHAT_RETENTION_DAYS after the last contact.

Databases created before this policy have documents without expiresAt, which a TTL index never deletes. Backfill them once (idempotent, --dry-run prints counts only):

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

Without MONGODB_URI, POST /api/chat and the form APIs continue to work; persistence calls are skipped silently.

Verify the connection:

npm run check:mongodbcurl http://localhost:3000/api/status

Expected when configured correctly:

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

A successful chat response also includes conversationId.

MongoDB troubleshooting

1. Network Access on Atlas must include 0.0.0.0/0 for Vercel serverless.
2. The URI must include the database name: ...mongodb.net/frasma_chat?...
3. If you reset the Atlas user password, update both .env.local and Vercel, then redeploy.
4. URL-encode special characters in the password (@, #, %, etc.).
5. After changing Vercel env vars, trigger a new deployment; env changes are not applied to existing deployments automatically.

AI discovery and public MCP

Public discovery surfaces for agents and humans:

MCP tools (read-only + handoff)

• get_frasma_profile
• search_frasma_knowledge
• get_diagnostic_framework
• prepare_diagnostic_summary — validates a diagnosis and returns handoff URLs; never sends email
• prepare_project_brief — validates the process brief used for a quote; never sends email

Example Cursor / Claude Desktop remote config:

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

For stdio-only clients:

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

Directory listing (after production deploy)

1. Confirm /for-agents, /servizi, /llms.txt, /llms-it.txt, and /api/mcp respond in production.
2. Smoke: curl -H 'Accept: text/markdown' -H 'Accept-Language: it' https://www.frasma.org/servizi/ddt-erp (Italian DDT/Mago copy), plus an MCP initialize + tools/list against /api/mcp.
3. Submit the server to relevant MCP directories with the short description from /for-agents (mention the services hub).
4. Keep the agent-skills digest in sync when SKILL.md changes (shasum -a 256).

Quality checks:

npm run lintnpm testnpm run build

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.