NewCrm MCP 서버 파운데이션

이 프로젝트는 기존 NewCrm CRM을 위한 별도의 MCP 서버입니다. CRM 코드베이스를 수정하지 않으며 MongoDB에 직접 연결하지 않습니다.

현재 범위는 향후 MCP 통합을 위한 깔끔한 기반으로 의도적으로 제한되어 있습니다.

아키텍처

ChatGPT Work ↓ OAuth 2.1 ↓ NewCrm MCP 서버 ↓ 기존 NewCrm 백엔드 API ↓ MongoDB

MCP 서버는 가능한 한 기존 백엔드 API 계층을 통해 기존 CRM과 통신하도록 설계되었습니다.

Related MCP server: @kemosoft/mcp-heymax-crm

현재 상태

이 프로젝트는 의도적으로 다음을 포함하지 않습니다:

• OAuth 구현

• MCP 도구

• HubSpot 통합

• 쓰기 작업

• 생성, 업데이트 또는 삭제 작업

• MongoDB 접근

• 대량 내보내기

• 웹훅

• 일괄 업데이트

프로젝트 구조

NewCrm-MCP/
├── src/
│   ├── audit/
│   │   └── logger.js
│   ├── auth/
│   │   └── tokenValidator.js
│   ├── config/
│   │   └── env.js
│   ├── permissions/
│   │   └── roleDefinitions.js
│   ├── services/
│   │   └── crmApiClient.js
│   ├── tools/
│   │   └── index.js
│   └── server.js
├── .env.example
├── .gitignore
├── package.json
├── README.md
└── node_modules/

설치

1. 프로젝트 폴더에서 터미널을 엽니다.

2. 종속성을 설치합니다:

npm install

환경 변수

예시 파일을 복사하고 로컬 .env 파일에 값을 설정합니다:

copy .env.example .env

.env 파일에는 다음과 같은 값이 포함되어야 합니다:

• PORT

• HOST

• NODE_ENV

• CRM_API_BASE_URL=https://www.jtcrm.in/api

• MCP_SERVER_NAME

• MCP_SERVER_VERSION

• LOG_LEVEL

• CRM_API_TIMEOUT_MS

시크릿이나 실제 토큰을 소스 제어에 커밋하지 마십시오. 영구 관리자 JWT나 프로덕션 자격 증명을 프로젝트에 저장하지 마십시오.

CRM API 통합

이 프로젝트는 기존 NewCrm 백엔드 API에 대한 안전한 읽기 전용 접근을 위한 재사용 가능한 CRM API 클라이언트를 포함합니다.

현재 지원되는 엔드포인트:

• GET /api/leads

이 서비스는 의도적으로 명시적으로 구성된 엔드포인트로만 제한됩니다. MCP 사용자로부터 임의의 URL을 허용하지 않습니다.

사용 예시:

import { getLeads } from "./src/services/crmApiClient.js";

const result = await getLeads({
  authToken: process.env.CRM_API_TEST_AUTH_TOKEN,
});

이렇게 하면 직접적인 MongoDB 접근과 쓰기 작업을 피하면서 향후 CRM API 호출을 위해 통합을 재사용할 수 있습니다.

안전한 테스트 지침

개발 또는 테스트를 위해 호출자 또는 로컬 임시 환경 값에서 런타임에 사용자 범위의 JWT를 전달하십시오. .env에 공유 관리자 토큰을 넣지 마십시오.

로컬 테스트 흐름 예시:

$env:CRM_API_TEST_AUTH_TOKEN="<user_jwt_here>"
node --input-type=module -e "import { getLeads } from './src/services/crmApiClient.js'; const result = await getLeads({ authToken: process.env.CRM_API_TEST_AUTH_TOKEN }); console.log(result);"

서비스는 토큰 자체를 절대 로깅하지 않으며 호출자가 제공할 때만 x-auth-token 헤더를 전송합니다.

서버 실행

npm start

선택적 개발 모드:

npm run dev

/mcp 작동 방식

이 프로젝트는 Streamable HTTP 전송과 함께 공식 MCP SDK를 사용합니다.

서버는 /mcp에 단일 MCP 엔드포인트를 노출합니다.

• POST /mcp는 MCP JSON-RPC 초기화 및 후속 요청을 처리합니다.

• 초기화 요청이 수신되면 새 세션이 생성됩니다.

• 각 세션은 연결된 Streamable HTTP 전송을 저장합니다.

• DELETE /mcp는 더 이상 필요하지 않은 세션을 닫습니다.

• GET /mcp는 이 파운데이션이 아직 스트리밍 GET 요청을 지원하지 않으므로 현재 405 Method Not Allowed를 반환합니다.

이는 CRM 기능을 조기에 추가하지 않고 향후 도구 및 백엔드 통합을 위한 올바른 기반입니다.

서버 테스트

서버를 시작한 후 성공적으로 수신 대기 중인지 확인합니다:

curl -i http://127.0.0.1:3002/mcp

예상 동작:

• 서버는 /mcp에 대한 GET 요청에 HTTP 405로 응답해야 합니다.

• 서버는 호환 가능한 클라이언트가 연결되면 MCP 초기화 및 JSON-RPC 트래픽에 대한 POST 요청도 수락해야 합니다.

성공적인 시작은 다음과 유사한 로그로 표시됩니다:

{"timestamp":"...","level":"info","message":"NewCrm MCP foundation server started","host":"127.0.0.1","port":3002,"endpoint":"/mcp"}

참고 사항

이 저장소는 의도적으로 기존 NewCrm 프로젝트와 분리되어 있습니다. 직접적인 데이터베이스 접근이나 CRM 특정 비즈니스 로직을 포함하지 않는 독립형 MCP 파운데이션 서버입니다.