nestr-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with the Nestr MCP Server.

Project Overview

This is an MCP (Model Context Protocol) server that connects AI assistants (Claude, Cursor, etc.) to Nestr workspaces. It wraps the Nestr REST API and exposes it as MCP tools.

Package: @nestr/mcp Landing page: https://mcp.nestr.io Nestr API docs: https://app.nestr.io/api/docs

Development Commands

# Install dependencies
npm install

# Development (stdio transport)
npm run dev

# Development (HTTP server for mcp.nestr.io)
npm run dev:http

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Test with MCP Inspector
npm run inspect

# Production (stdio)
npm start

# Production (HTTP)
npm run start:http

Testing

Tests use vitest + supertest. Run npm test before pushing — CI runs tests on every PR and on publish.

tests/
  http-server.test.ts           # HTTP integration tests (supertest against Express app)
  helpers/
    mock-store.ts               # In-memory OAuthStore for tests
  unit/
    oauth.test.ts               # PKCE, constantTimeCompare, validateRedirectUri
    http-helpers.test.ts        # getAuthToken, escapeHtml, isValidGtmId
    tools-helpers.test.ts       # compactResponse, enrichHints, stripDescriptionFields
    api-client.test.ts          # NestrClient with mocked fetch

Key conventions:

• Mock getStore() from src/oauth/store.js using the in-memory mock store — never hit Redis/filesystem in tests
• Mock globalThis.fetch with vi.stubGlobal for NestrClient and OAuth proxy tests
• The Express app is exported from src/http.ts and the startup IIFE is guarded by isDirectRun so importing it for tests doesn't start a server
• src/http.ts exports session helpers (sessions, sweepStaleSessions, SSE_DEAD_IDLE_TIMEOUT_MS) for direct unit testing of the stale-session sweep. Concurrent sessions per (auth token, client name) are intentional — an initialize must never close another connection's session