Add linting documentation and pre-commit hooks (modelcontextprotocol#177)

## Summary

This PR improves the developer experience by adding clear linting
documentation and optional pre-commit hooks to catch issues before CI.
Helpful to avoid fighting Claude Code / Copilot on "please make sure
linting passes CI".

## Changes

- Updated `README.md` with:
  - Go 1.23.x requirement (was "1.18 or later")
  - golangci-lint v1.61.0 in prerequisites
  - New Development section with linting instructions
  
- Updated `CLAUDE.md` with:
  - Development Setup section
  
- Added `.githooks/pre-commit`:
  - Runs golangci-lint and gofmt checks
  - References README for installation instructions
  - Can be bypassed with `--no-verify` when needed

## Test Plan

- [x] Verified pre-commit hook blocks commits when golangci-lint is
missing
- [x] Confirmed hook shows clear error message pointing to README
- [x] Tested that linting passes with Go 1.23.0 and golangci-lint
v1.61.0
- [x] Verified gofmt correctly identifies formatting issues

Co-authored w/ Claude Code

---------

Co-authored-by: Charles Lowell <[email protected]>

Author: tadasant

.githooks/pre-commit

@@ -0,0 +1,35 @@
+#!/bin/bash
+
+# Pre-commit hook for MCP Registry
+# Runs linting and formatting checks before allowing commits
+
+set -e
+
+echo "Running pre-commit checks..."
+
+# Check if golangci-lint is installed
+if ! command -v golangci-lint &> /dev/null; then
+    echo "❌ golangci-lint is not installed!"
+    echo "See README.md Prerequisites section for installation instructions."
+    exit 1
+fi
+
+# Run golangci-lint
+echo "Running golangci-lint..."
+if ! golangci-lint run --timeout=5m; then
+    echo "❌ Linting failed! Please fix the issues above."
+    exit 1
+fi
+
+# Check formatting
+echo "Checking Go formatting..."
+UNFORMATTED=$(gofmt -s -l .)
+if [ -n "$UNFORMATTED" ]; then
+    echo "❌ The following files need formatting:"
+    echo "$UNFORMATTED"
+    echo ""
+    echo "Run 'gofmt -s -w .' to fix formatting issues."
+    exit 1
+fi
+
+echo "✅ All pre-commit checks passed!"

CLAUDE.md

@@ -5,6 +5,22 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Overview
 MCP Registry is a community-driven registry service for Model Context Protocol (MCP) servers. It provides a centralized repository for discovering and managing MCP implementations.
 
+## Development Setup
+
+### Prerequisites
+- **Go 1.23.x** - The project requires this specific version (check with `go version`)
+  - Consider using a Go version manager like `g` or `gvm` if you work on multiple projects
+- **golangci-lint v1.61.0** - Install with:
+  ```bash
+  curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.61.0
+  ```
+
+### Git Hooks (Optional)
+To run linting automatically before commits:
+```bash
+git config core.hooksPath .githooks
+```
+
 ## Common Development Commands
 
 ### Build
@@ -46,16 +62,18 @@ export BEARER_TOKEN=your_github_token_here
 
 ### Lint
 ```bash
-# Install golangci-lint if needed
-curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.61.0
-
-# Run linting
+# Run linting (same as CI)
 golangci-lint run --timeout=5m
 
 # Check formatting
 gofmt -s -l .
+
+# Fix formatting issues
+gofmt -s -w .
 ```
 
+**Note**: The project uses golangci-lint v1.61.0 with 62 enabled linters. Always run linting locally before pushing to avoid CI failures.
+
 ## Architecture Overview
 
 The codebase follows a clean architecture pattern:

README.md

@@ -24,10 +24,16 @@ The MCP Registry service provides a centralized repository for MCP server entrie
 
 ### Prerequisites
 
-- Go 1.18 or later
+- Go 1.23.x (required - check with `go version`)
 - MongoDB
 - Docker (optional, but recommended for development)
 
+For development:
+- golangci-lint v1.61.0 - Install with:
+  ```bash
+  curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.61.0
+  ```
+
 ## Running
 
 The easiest way to get the registry running is to use `docker compose`. This will setup the MCP Registry service, import the seed data and run MongoDB in a local Docker environment.
@@ -54,6 +60,33 @@ This will create the `registry` binary in the current directory. You'll need to
 
 By default, the service will run on `http://localhost:8080`.
 
+## Development
+
+### Linting
+
+The project uses golangci-lint with extensive checks. Always run linting before pushing:
+
+```bash
+# Run all linters (same as CI)
+golangci-lint run --timeout=5m
+
+# Check formatting
+gofmt -s -l .
+
+# Fix formatting
+gofmt -s -w .
+```
+
+### Git Hooks (Optional)
+
+To automatically run linting before commits:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+This will prevent commits that fail linting or have formatting issues.
+
 ## Project Structure
 
 ```