AGENTS.md · neondatabase/mcp-server-neon

Sections

1. Project Overview
2. Development Commands
3. Architecture
4. Tool arguments
5. Adding New Tools
6. Environment Configuration
7. Project Structure
8. Repository Notes (ai-notes/)
9. Important Notes
10. Remote MCP Server (Vercel)
11. GitHub Workflows

First lines (shown under the repo's MIT license)

# AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

## Project Overview

This is the **Neon MCP Server** - a Model Context Protocol server that bridges natural language requests to the Neon API, enabling LLMs to manage Lakebase Postgres databases on Neon through conversational commands. The project implements remote (SSE/Streamable HTTP) MCP server transports with OAuth authentication support.

**Architecture Note**: The project is a Next.js application at the repository root, deployed on Vercel serverless infrastructure and accessible at `mcp.neon.tech`.

## Development Commands

All commands should be run from the repository root. The project uses [pnpm](https://pnpm.io) as the package manager, pinned via Corepack. Run `corepack enable` to activate it.

> **Troubleshooting:** If `pnpm install` fails with registry or network errors, check whether your npm registry is configured to use the Databricks proxy. Set the registry in `~/.npmrc` or `.npmrc`.

### Building and Running

```bash
pnpm install

# Start the Next.js dev server (for the remote MCP server)
pnpm dev
```

### Formatting, Linting, and Type Checking

```bash
# Check formatting (runs in CI)
pnpm fmt:check

# Auto-fix formatting
pnpm fmt

# Lint
pnpm lint

# Auto-fix lint + formatting together
pnpm lint:fix

# Type check
pnpm typecheck

# Check for unused code and dependencies
pnpm knip

# Auto-fix unused exports/dependencies
pnpm knip:fix
```

### Testing

```bash
# Run full test suite (unit + integration + e2e; used in CI)
pnpm test

# Run unit tests
pnpm test:unit

# Run integration tests
pnpm test:integration

# Run MCP protocol e2e tests (real tool calls over MCP protocol)
pnpm test:e2e:mcp

# Run live MCP → Neon E2E tests (requires .env.test)
pnpm test:e2e:live

# Run website e2e tests (Playwright; provisions/validates ephemeral DB first)
pnpm test:e2e:web

# Run all e2e tests
pnpm test:e2e
```

### Live MCP → Neon E2E tests

`pnpm test:e2e:live` runs a real MCP client and server over the SDK's in-memory
transport, while every tool call reaches the real Neon Management API and a real
temporary Neon database. This is more deterministic than starting an HTTP server
and shelling through `mcporter`, while still covering MCP schemas, tool
registration, handlers, `@neon/sdk`, connection-string resolution, and SQL.

Set up the dedicated disposable test organization:

```bash
cp .env.test.example .env.test
# Fill in NEON_API_KEY with an org-scoped key for the disposable test org.
# NEON_TEST_ORG_ID is inferred for org-scoped keys; set it for user keys.
pnpm test:e2e:live
```

The test only loads this repository's `.env.test`; it must not inspect parent or
workspace-global environment files. The suite asks `@neon/sdk` for the
organization attached to an org-scoped key.

The suite always creates a uniquely named `smoke-mcp-live-*` project first and
deletes it at the end. Cleanup runs from `afterAll` even when an assertion fails,
uses `@neon/sdk` to verify the project name before deletion, and refuses to
delete projects without the smoke prefix. Never point these variables at a
personal or production organization, and never commit `.env.test`.

For same-repository pull requests, `.github/workflows/pr.yml` maps the
repository secret `NEON_TEST_API_KEY` to `NEON_API_KEY` for this step. Fork and
Dependabot PRs skip the live suite because GitHub does not safely expose
repository secrets to untrusted PR code.

### Live API-key smoke testing with mcporter

To verify a local MCP server against the real Neon API, start it with `NEON_API_KEY` in its environment (for example, `pnpm exec next dev --port 3031`), then use `npx mcporter` from an untracked temporary directory to register `http://127.0.0.1:3031/mcp` with the header `Authorization: Bearer $NEON_API_KEY`. Create a clearly prefixed project in the approved smoke-test organization, exercise the changed tools (including project and branch lifecycle), then delete the project and the temporary mcporter config directory. Never print or commit the API key, connection strings, or the generated config.

### Testing Pyramid Rules

The repository follows this hierarchy:

1. **E2E first** (highest confidence):
   - `test:e2e:live`: MCP client + server + real Neon API/project/database lifecycle. Opt-in because it requires a dedicated test-org API key.
   - `test:e2e:mcp`: MCP client + server protocol tests that perform real tool calls.
   - `test:e2e:web`: Playwright tests for website and HTTP endpoints.
2. **Integration second**:
   - Deterministic handler contract tests, typically with mocked external dependencies.
3. **Unit third**:
   - Fast tests for pure logic and validation edge cases.

Use file naming to classify tiers:

- `*.e2e.test.ts` for MCP protocol end-to-end tests
- `*.integration.test.ts` for integration tests
- `*.test.ts` for unit tests

Keep the default unit/integration suites deterministic. The explicitly named
live Neon E2E step is the only merge check that depends on external
infrastructure.

**Unit and integration tests** use [Vitest](https://vitest.dev/) and live in `mcp/__tests__/`. Configuration is in `vitest.config.ts`.

**E2E tests** use [Playwright](https://playwright.dev/) and live in `e2e/`. Configuration is in `playwright.config.ts`.

- **Global setup** (`e2e/global-setup.ts`): Provisions an ephemeral Postgres database via [Instagres](https://instagres.com). The connection string is written to `.env.e2e` (gitignored) and passed to the Next.js dev server. It also starts the docs fixture server (see below).
- **Docs fixture** (`e2e/docs-fixture.ts`): `search_docs`, `get_doc`, and `send_feedback` fetch server-side, so `request.route()` cannot intercept them, and a test calling them would otherwise depend on neon-agent, neon.com, and the feedback service being up — which merge-gating tests must not. Global setup serves canned site search responses (chosen by query), one page (`/docs/reference/glossary.md`), and a feedback endpoint on port `3101` (`E2E_DOCS_PORT` to change it, and it fails loudly if the port is taken). `playwright.config.ts` points the dev server's `NEON_SITE_SEARCH_URL`, `NEON_DOCS_BASE_URL`, and `NEON_FEEDBACK_URL` at it. Those URLs must be set in `webServer.env`, not in global setup: Playwright starts the web server as a plugin task, which runs **before** global setup, so anything global setup adds to `process.env` reaches the dev server too late.
- **No secrets needed**: The e2e infrastructure is fully self-contained. Instagres databases expire after 72 hours; no explicit teardown is required.
- **Reuse across runs**: If `.env.e2e` already exists, global-setup reuses it instead of re-provisioning. Delete the file to force a fresh database.
- **CI**: The PR workflow runs format, lint, knip, `pnpm test`, live Neon E2E for trusted same-repo PRs, and build before merge.

## Architecture

### Core Components

1. **MCP Server (`mcp/server/index.ts`)**
   - Creates and configures the MCP server instance
   - Registers all tools and resources from centralized definitions
   - Implements error handling and observability (Sentry, analytics)
   - Each tool call is tracked and wrapped in error handling

   **Account Resolution (`mcp/server/account.ts`)**:
   - Resolves user/org account info from Neon API auth details
   - Handles org accounts, personal accounts, and project-scoped API keys
   - Falls back gracefully when project-scoped keys cannot access account-level endpoints

2. **Tools System (`mcp/tools/`)**