Frasma

Official5 tools

by francemazzi · TypeScript

Read-only Frasma MCP: profile, knowledge search, diagnostic handoff. No email.

io.github.francemazzi/frasma — Read-only Frasma MCP Server

This is a read-only Frasma MCP server that provides profile access, knowledge search, and a diagnostic handoff. It has no email functionality. The project is a Next.js application and is bootstrapped with create-next-app. The repository includes five tools.

🛠️ Key Features

Read-only MCP server behavior
Profile access
Knowledge search
Diagnostic handoff
No email

🚀 Use Cases

Retrieving a Frasma profile
Performing knowledge searches
Passing off diagnostics for follow-up work

⚡ Developer Benefits

Built as a Next.js project (create-next-app)
Suitable for running locally via the Next.js dev server (npm run dev)
Provides 5 MCP tools

⚠️ Limitations

Read-only: does not support write operations (implied by “Read-only”)
No email support
Detailed tool behaviors are not described in the provided excerpt

Captured live from the server via tools/list.

get_frasma_profile

Returns the verified public profile, focus areas, sectors, commercial boundaries, and discovery URLs for Frasma.

Parameters1

locale

string

optional

Response language: it or en. Defaults to en.

Raw schema

{
  "type": "object",
  "properties": {
    "locale": {
      "description": "Response language: it or en. Defaults to en.",
      "type": "string",
      "enum": [
        "it",
        "en"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_frasma_knowledge

Searches verified Frasma services, sectors, case studies, methodology, fit criteria, and commercial boundaries. Use before making factual claims.

Parameters3

query	string	required	Search query for verified Frasma knowledge, e.g. DDT ERP or HACCP procedures.
locale	string	optional	Response language: it or en. Defaults to en.
pagePath	string	optional	Optional canonical site path to scope results, e.g. /servizi/ddt-erp.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Search query for verified Frasma knowledge, e.g. DDT ERP or HACCP procedures."
    },
    "locale": {
      "description": "Response language: it or en. Defaults to en.",
      "type": "string",
      "enum": [
        "it",
        "en"
      ]
    },
    "pagePath": {
      "description": "Optional canonical site path to scope results, e.g. /servizi/ddt-erp.",
      "type": "string",
      "pattern": "^\\/.*"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_diagnostic_framework

Returns the diagnostic method, evidence to collect, fit criteria, and commercial limits.

Parameters1

locale

string

optional

Response language: it or en. Defaults to en.

Raw schema

{
  "type": "object",
  "properties": {
    "locale": {
      "description": "Response language: it or en. Defaults to en.",
      "type": "string",
      "enum": [
        "it",
        "en"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

prepare_diagnostic_summary

Validates a complete diagnostic summary and returns a handoff payload. Does not send email. Map the diagnosis to a process brief; the user must confirm before POST /api/request-process-assessment.

Parameters20

clientName	string	required	Client full name.
clientEmail	string	required	Client work email.
clientCompany	string	optional	Client company name, if known.
sector	string	required	Business sector, e.g. manufacturing or food quality.
process	string	required	Short name of the process under diagnosis, e.g. delivery notes into ERP.
currentWorkflow	string	required	How the process is done today, including people, tools, and handoffs.
bottlenecks	array	required	Observed bottlenecks, one item per string.
currentSystems	array	required	Systems already in use, e.g. email, PDF, Mago Zucchetti.
volumesAndFrequency	string	required	Volumes and frequency, e.g. about 40 DDT per day.
baselineMetrics	array	required	Baseline metrics before any Frasma work, e.g. minutes per document.
dataAvailable	array	required	Data that can be shared for a prototype, preferably anonymized samples.
constraints	array	required	Hard constraints, e.g. human validation before ERP import.
desiredOutcomes	array	required	Desired outcomes without invented savings or guarantees.
needCategories	array	required	One or more Frasma need categories that fit the diagnosis.
opportunities	array	required	Concrete opportunities that follow from the evidence.
recommendations	array	required	Recommended next steps for a limited prototype or discovery.
openQuestions	array	required	Open questions still to confirm with the client.
nextSteps	array	required	Agreed next steps after reviewing this summary.
language	string	required	Language of the diagnostic summary: it or en.
honeypot	string	optional	Anti-spam trap. Must be empty or omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "clientName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Client full name."
    },
    "clientEmail": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Client work email."
    },
    "clientCompany": {
      "description": "Client company name, if known.",
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "sector": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160,
      "description": "Business sector, e.g. manufacturing or food quality."
    },
    "process": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240,
      "description": "Short name of the process under diagnosis, e.g. delivery notes into ERP."
    },
    "currentWorkflow": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "How the process is done today, including people, tools, and handoffs."
    },
    "bottlenecks": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Observed bottlenecks, one item per string."
    },
    "currentSystems": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Systems already in use, e.g. email, PDF, Mago Zucchetti."
    },
    "volumesAndFrequency": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Volumes and frequency, e.g. about 40 DDT per day."
    },
    "baselineMetrics": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Baseline metrics before any Frasma work, e.g. minutes per document."
    },
    "dataAvailable": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Data that can be shared for a prototype, preferably anonymized samples."
    },
    "constraints": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Hard constraints, e.g. human validation before ERP import."
    },
    "desiredOutcomes": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Desired outcomes without invented savings or guarantees."
    },
    "needCategories": {
      "minItems": 1,
      "maxItems": 7,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "document_erp",
          "workflow",
          "ticketing",
          "dataset_benchmark",
          "ai_optimization",
          "company_wiki",
          "ai_presence"
        ],
        "description": "Frasma need category: document_erp, workflow, ticketing, dataset_benchmark, ai_optimization, company_wiki, or ai_presence."
      },
      "description": "One or more Frasma need categories that fit the diagnosis."
    },
    "opportunities": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Concrete opportunities that follow from the evidence."
    },
    "recommendations": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Recommended next steps for a limited prototype or discovery."
    },
    "openQuestions": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Open questions still to confirm with the client."
    },
    "nextSteps": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 800
      },
      "description": "Agreed next steps after reviewing this summary."
    },
    "language": {
      "type": "string",
      "enum": [
        "it",
        "en"
      ],
      "description": "Language of the diagnostic summary: it or en."
    },
    "honeypot": {
      "description": "Anti-spam trap. Must be empty or omitted.",
      "type": "string",
      "maxLength": 0
    }
  },
  "required": [
    "clientName",
    "clientEmail",
    "sector",
    "process",
    "currentWorkflow",
    "bottlenecks",
    "currentSystems",
    "volumesAndFrequency",
    "baselineMetrics",
    "dataAvailable",
    "constraints",
    "desiredOutcomes",
    "needCategories",
    "opportunities",
    "recommendations",
    "openQuestions",
    "nextSteps",
    "language"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

prepare_project_brief

Validates the process brief used for a quote (name, email, process, optional company/role/systems/volume). Does not send email. The user must confirm before POST /api/request-process-assessment.

Parameters7

name	string	required	Client full name.
clientEmail	string	required	Client work email.
company	string	optional	Client company name, if known.
role	string	optional	Client role, if known.
process	string	required	Process to evaluate, at least 20 characters: trigger, work today, and desired outcome.
systems	string	optional	Systems already in use, e.g. Outlook and ERP.
volume	string	optional	Volumes or frequency, e.g. 80 documents per week.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "Client full name."
    },
    "clientEmail": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "description": "Client work email."
    },
    "company": {
      "description": "Client company name, if known.",
      "type": "string",
      "maxLength": 120
    },
    "role": {
      "description": "Client role, if known.",
      "type": "string",
      "maxLength": 120
    },
    "process": {
      "type": "string",
      "minLength": 20,
      "maxLength": 2000,
      "description": "Process to evaluate, at least 20 characters: trigger, work today, and desired outcome."
    },
    "systems": {
      "description": "Systems already in use, e.g. Outlook and ERP.",
      "type": "string",
      "maxLength": 500
    },
    "volume": {
      "description": "Volumes or frequency, e.g. 80 documents per week.",
      "type": "string",
      "maxLength": 500
    }
  },
  "required": [
    "name",
    "clientEmail",
    "process"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md8 KBView on GitHub

smithery badge

Frasma on Smithery

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

Getting Started

First, run the development server:

bash

npm run dev
# or
yarn 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:

bash

# Destination email (defaults to francemazzi@gmail.com)
MEETING_NOTIFICATION_EMAIL=francemazzi@gmail.com

# Sender identity (defaults to SMTP_USER if using SMTP)
MEETING_FROM_EMAIL=francemazzi@gmail.com

# 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
SMTP_USER=francemazzi@gmail.com
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

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):

bash

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

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:

Create a free M0 cluster on MongoDB Atlas (recommended region: Frankfurt or Ireland).
Create a database user with read/write access.
In Network Access, allow 0.0.0.0/0 (required for Vercel serverless).
Copy the connection string and set these environment variables locally and on Vercel:

bash

MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/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):

bash

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

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

Verify the connection:

bash

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

Expected when configured correctly:

json

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

A successful chat response also includes conversationId.

MongoDB troubleshooting

Network Access on Atlas must include 0.0.0.0/0 for Vercel serverless.
The URI must include the database name: ...mongodb.net/frasma_chat?...
If you reset the Atlas user password, update both .env.local and Vercel, then redeploy.
URL-encode special characters in the password (@, #, %, etc.).
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:

Resource	URL
Agents hub	https://www.frasma.org/for-agents
Services hub	https://www.frasma.org/servizi
Case studies	https://www.frasma.org/casi
llms.txt	https://www.frasma.org/llms.txt
llms-it.txt	https://www.frasma.org/llms-it.txt
Home markdown	`GET /` with `Accept: text/markdown`
OpenAPI	https://www.frasma.org/openapi.json
API catalog	https://www.frasma.org/.well-known/api-catalog
Agent skills	https://www.frasma.org/.well-known/agent-skills/index.json
MCP (Streamable HTTP)	https://www.frasma.org/api/mcp

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:

json

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

For stdio-only clients:

json

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

Directory listing (after production deploy)

Confirm /for-agents, /servizi, /llms.txt, /llms-it.txt, and /api/mcp respond in production.
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.
Submit the server to relevant MCP directories with the short description from /for-agents (mention the services hub).
Keep the agent-skills digest in sync when SKILL.md changes (shasum -a 256).

Quality checks:

bash

npm run lint
npm test
npm 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.

Install

Tools (5)

get_frasma_profilesearch_frasma_knowledgeget_diagnostic_frameworkprepare_diagnostic_summaryprepare_project_brief

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://www.frasma.org/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.francemazzi/frasma — Read-only Frasma MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

get_frasma_profile

search_frasma_knowledge

get_diagnostic_framework

prepare_diagnostic_summary

prepare_project_brief

Getting Started

Process brief (quote request)

Required environment variables

Diagnostic chat agent

Chat persistence (MongoDB Atlas)

MongoDB troubleshooting

AI discovery and public MCP

MCP tools (read-only + handoff)

Directory listing (after production deploy)

Learn More

Deploy on Vercel

Install

Remote endpoint

Related servers