frasma

Smithery의 Frasma

이것은 create-next-app으로 부트스트랩한 Next.js 프로젝트입니다.

시작하기

먼저 개발 서버를 실행하세요:

npm run dev
# or
yarn dev

브라우저로 http://localhost:3000을 열면 결과를 확인할 수 있습니다.

pages/index.tsx를 수정하여 페이지 편집을 시작할 수 있습니다. 파일을 편집하면 페이지가 자동으로 업데이트됩니다.

API 라우트는 http://localhost:3000/api/hello에서 접근할 수 있습니다. 이 엔드포인트는 pages/api/hello.ts에서 편집할 수 있습니다.

pages/api 디렉터리는 /api/*에 매핑됩니다. 이 디렉터리의 파일은 React 페이지가 아닌 API 라우트로 처리됩니다.

Related MCP server: MCP Ops Agent

프로세스 브리프(견적 요청)

랜딩 폼과 채팅 위젯은 모두 POST /api/request-process-assessment로 프로세스 브리프를 제출합니다. Francesco는 이 브리프를 사용해 견적을 준비합니다.

필드: 이름, 업무 이메일, 선택 사항인 회사 및 역할, 프로세스(필수), 선택 사항인 현재 도구와 규모.

MONGODB_URI가 설정되면 동일한 엔드포인트가 users를 upsert하고, leads를 삽입하며, project_brief_submitted를 기록합니다.

필수 환경 변수

프로젝트 루트에 .env.local 파일을 만들어 다음을 입력하세요:

# 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

참고:

• 프로덕션에서는 호스팅 제공업체(예: Vercel)에서 이 변수들을 설정해야 합니다.

• SMTP와 Resend 중 하나도 구성되지 않으면 API는 오류를 반환하고 팝업이 사용자에게 오류를 표시합니다.

진단 채팅 에이전트

웹사이트 채팅은 프로세스 진단 어시스턴트입니다. lib/knowledge/의 이중 언어, 버전 관리형 지식 베이스를 사용하여 다음을 수행합니다:

• 운영 병목 지점을 파악합니다;

• 워크플로, 시스템, 규모, 기준 지표, 데이터 및 제약 조건을 수집합니다;

• 요구 사항을 Frasma 역량에 매핑합니다;

• 편집 가능한 프로세스 브리프를 준비합니다;

• 사용자가 명시적으로 검토한 후에만 해당 브리프를 POST /api/request-process-assessment에 제출합니다.

어시스턴트가 시간 초과되면 위젯은 대화 기록에서 미리 채워진 동일한 프로세스 브리프 양식을 표시합니다(추가 LLM 호출 없음).

각 브라우저 세션은 localStorage에 conversationId를 저장합니다. 메시지는 공식 Node.js 드라이버를 통해 MongoDB Atlas에 서버 측에서 영구 저장됩니다. 다시 열면 위젯은 GET /api/conversations/:id를 통해 대화를 복원합니다. MongoDB가 구성되지 않은 경우 채팅은 상태 비저장 모드에서 계속 작동합니다.

지식 베이스나 진단 예시에 가격, 보장된 절감액, 고객 비밀, 자격 증명 또는 제3자의 개인 데이터를 추가하지 마세요.

필수 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 클러스터를 생성합니다(권장 리전: Frankfurt 또는 Ireland).

2. 읽기/쓰기 권한이 있는 데이터베이스 사용자를 생성합니다.

3. Network Access에서 0.0.0.0/0을 허용합니다(Vercel serverless에 필요).

4. 연결 문자열을 복사하고 다음 환경 변수를 로컬과 Vercel에 설정합니다:

MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/frasma_chat?retryWrites=true&w=majority
CHAT_RETENTION_DAYS=90

conversations.expiresAt의 인덱스와 TTL 정책은 첫 사용 시 자동으로 생성됩니다.

MONGODB_URI가 없어도 POST /api/chat과 양식 API는 계속 작동하며 영속성 호출은 자동으로 건너뜁니다.

연결을 확인하세요:

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

올바르게 구성된 경우의 예상 결과:

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

성공적인 채팅 응답에는 conversationId도 포함됩니다.

MongoDB 문제 해결

1. Atlas의 Network Access에는 Vercel serverless용 0.0.0.0/0이 포함되어야 합니다.

2. URI에는 데이터베이스 이름이 포함되어야 합니다: ...mongodb.net/frasma_chat?...

3. Atlas 사용자 비밀번호를 재설정한 경우 .env.local과 Vercel을 모두 업데이트한 후 다시 배포하세요.

4. 비밀번호의 특수 문자(@, #, % 등)를 URL 인코딩하세요.

5. Vercel 환경 변수를 변경한 후에는 새 배포를 실행하세요. 환경 변수 변경은 기존 배포에 자동으로 적용되지 않습니다.

AI 디스커버리 및 공개 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' https://www.frasma.org/ 및 https://www.frasma.org/servizi/ddt-erp, 그리고 /api/mcp에 대한 MCP initialize + tools/list를 실행하세요.

3. /for-agents의 짧은 설명을 사용해 관련 MCP 디렉터리에 서버를 등록하세요(서비스 허브를 언급).

4. SKILL.md가 변경될 때 agent-skills 다이제스트를 동기화하세요(shasum -a 256).

품질 검사:

npm run lint
npm test
npm run build

자세히 알아보기

Next.js에 대해 더 알아보려면 다음 리소스를 참조하세요:

• Next.js 문서 - Next.js 기능과 API에 대해 알아봅니다.

• Learn Next.js - 대화형 Next.js 튜토리얼입니다.

Next.js GitHub 저장소를 확인해 보세요 - 피드백과 기여를 환영합니다!

Vercel에 배포

Next.js 앱을 배포하는 가장 쉬운 방법은 Next.js 제작자들이 만든 Vercel 플랫폼을 사용하는 것입니다.

자세한 내용은 Next.js 배포 문서를 확인하세요.