neondatabase/mcp-server-neon | awesome-claude-md

Category: Developer Tooling Source: neondatabase/mcp-server-neon CLAUDE.md: View Original License: MIT License Why it's exemplary: Production-grade MCP server documentation demonstrating dual-purpose architecture (remote server + local CLI), comprehensive tool development patterns, and stateless serverless design principles.

Key Features That Make This Exemplary

1. Dual-Purpose Architecture Documentation

Remote Server Mode: HTTP/SSE server for LLM integration with OAuth flow
Local CLI Mode: Command-line interface for direct API interaction
Stateless Design Philosophy: Explicit explanation of why context flows through LLM responses rather than server state
Transport Abstraction: Clear separation between MCP protocol and transport mechanisms

2. Comprehensive Tool Development Guide

Step-by-Step Creation: "Adding New Tools" section with complete walkthrough
Code Templates: TypeScript schema definitions with Zod validation examples
File Structure: Four distinct locations for tool registration clearly mapped
Handler Patterns: Proper typing and MCP protocol compliance demonstrated

3. MCP Protocol Best Practices

Annotations System: Demonstrates destructiveHint, idempotentHint, openWorldHint
Read-Only Mode: Filtering mechanism for tool availability based on context
Error Handling: MCP-specific error patterns and validation strategies
Schema Documentation: Inline descriptions for AI comprehension

4. Production Deployment Details

Vercel Integration: Complete serverless deployment configuration
Environment Variables: All required variables documented with purposes
OAuth Flow: Neon-specific authorization endpoints and token management
Tech Stack: Explicit dependencies (Next.js, Model Context Protocol SDK)

Specific Techniques to Learn

Tool Schema Definition

{
  name: "tool_name",
  description: "Clear description for AI understanding",
  inputSchema: z.object({
    param: z.string().describe("Inline description for the AI"),
  }),
}

Uses Zod for type-safe validation with AI-friendly descriptions.

Stateless Architecture Pattern

Why Stateless?
- Serverless deployment requires no persistent server state
- Context flows through LLM conversation history
- Each request is independent and self-contained

Architectural decision explicitly explained with rationale.

Tool Registration Flow

1. Define schema in schemas/ directory
2. Implement handler in handlers/ directory
3. Register in tools/index.ts
4. Export from index.ts

Four-step process ensures consistency across new tools.

Development Workflow

bun install              # Install dependencies
bun run start:cli $KEY   # Test locally with CLI mode
mcp-client <server-url>  # Test remote server integration

Complete development cycle from setup to testing.

Key Takeaways

Dual-Purpose Design: Document both server and CLI modes with clear use cases for each
Stateless Principles: Explain architectural decisions for serverless environments
Tool Development Templates: Provide boilerplate code with clear registration patterns
MCP Annotations: Use protocol-specific hints for AI assistant optimization
OAuth Integration: Document complete authentication flows for enterprise deployments

Unique Patterns

Stateless Design Explanation: Explicit discussion of why context doesn't persist on server
MCP Hint System: Advanced use of destructive/idempotent/openWorld annotations
Dual Transport Support: Same codebase serves both HTTP/SSE and CLI interfaces
Tool Creation Workflow: Step-by-step guide with file locations and code patterns

Educational Value

This example is particularly valuable for:

Teams building MCP server integrations with enterprise APIs
Developers designing stateless serverless architectures
Projects requiring both programmatic and CLI access patterns
Understanding MCP protocol best practices and annotations

Analysis