# NewCrm MCP Server Foundation

This project is a separate MCP server for the existing NewCrm CRM. It does not modify the CRM codebase and does not connect directly to MongoDB.

Current scope is intentionally limited to a clean foundation for future MCP integration.

## Architecture

ChatGPT Work
↓
OAuth 2.1
↓
NewCrm MCP Server
↓
Existing NewCrm Backend APIs
↓
MongoDB

The MCP server is designed to communicate with the existing CRM through the existing backend API layer wherever possible.

## Current status

The project intentionally does not include:

- OAuth implementation
- MCP tools
- HubSpot integration
- write operations
- create, update, or delete operations
- MongoDB access
- bulk exports
- webhooks
- batch updates

## Project structure

```text
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/
```

## Installation

1. Open a terminal in the project folder.
2. Install dependencies:

```bash
npm install
```

## Environment variables

Copy the example file and set values in your local `.env` file:

```bash
copy .env.example .env
```

The `.env` file should contain values such as:

- `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`

Do not commit secrets or real tokens to source control. Do not store a permanent admin JWT or any production credential in the project.

## CRM API integration

This project includes a reusable CRM API client for safe read-only access to the existing NewCrm backend APIs.

Current supported endpoint:

- `GET /api/leads`

The service is intentionally restricted to explicitly configured endpoints only. It does not accept arbitrary URLs from MCP users.

Example usage:

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

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

This keeps the integration reusable for future CRM API calls while avoiding direct MongoDB access and write operations.

## Safe testing guidance

For development or testing, pass a user-scoped JWT at runtime from the caller or a local ephemeral environment value. Do not put a shared admin token in `.env`.

Example local test flow:

```bash
$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);"
```

The service will never log the token itself and only sends the `x-auth-token` header when a caller provides it.

## Run the server

```bash
npm start
```

Optional development mode:

```bash
npm run dev
```

## How `/mcp` works

This project uses the official MCP SDK with Streamable HTTP transport.

The server exposes a single MCP endpoint at `/mcp`.

- `POST /mcp` handles MCP JSON-RPC initialization and follow-up requests.
- A new session is created when an initialization request is received.
- Each session stores its associated Streamable HTTP transport.
- `DELETE /mcp` closes a session when it is no longer needed.
- `GET /mcp` currently returns `405 Method Not Allowed` because this foundation does not yet support streaming GET requests.

This is the correct foundation for future tool and backend integrations without adding CRM functionality prematurely.

## Testing the server

After starting the server, confirm it is listening successfully:

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

Expected behavior:

- The server should respond with HTTP `405` for GET requests on `/mcp`.
- The server should also accept POST requests for MCP initialization and JSON-RPC traffic once a compatible client is connected.

A successful startup is indicated by logs similar to:

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

## Notes

This repository is intentionally isolated from the existing NewCrm project. It is a stand-alone MCP foundation server and does not include direct database access or CRM-specific business logic.