Consolidate documentation and remove redundancy (#222)

## Summary

This PR consolidates our documentation to reduce redundancy and
maintenance overhead:

- Removes the CLAUDE.md file with Import statement in favor of direct
README.md usage
- Merges CONTRIBUTING.md content into README.md's Contributing section  
- Migrates useful architecture and developer information from the old
CLAUDE.md to README.md
- Eliminates duplicated information between files

## Benefits

- Single source of truth in README.md reduces documentation drift
- Easier maintenance with all docs in one place
- Claude Code remains fully functional while reducing complexity

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: domdomegg

CLAUDE.md

@@ -1,121 +1,4 @@
 # CLAUDE.md
+_Guidance for Claude Code (claude.ai/code) when working in this repository. If it's also useful to humans (probably most things!), put the instructions in README.md instead._
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## 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 v2.3.1** - Install with:
-  ```bash
-  curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.3.1
-  ```
-
-### Git Hooks (Optional)
-To run linting automatically before commits:
-```bash
-git config core.hooksPath .githooks
-```
-
-## Common Development Commands
-
-### Build
-```bash
-# Build the registry application
-go build ./cmd/registry
-
-# Build with Docker
-docker build -t registry .
-
-# Build the publisher tool
-cd tools/publisher && ./build.sh
-```
-
-### Run
-```bash
-# Development with Docker Compose (recommended)
-docker compose up
-
-# Direct execution
-go run cmd/registry/main.go
-```
-
-### Test
-```bash
-# Unit tests
-go test -v -race -coverprofile=coverage.out -covermode=atomic ./internal/...
-
-# Integration tests
-./tests/integration/run.sh
-
-# Test API endpoints
-./scripts/test_endpoints.sh
-
-# Test publish endpoint (requires GitHub token)
-export BEARER_TOKEN=your_github_token_here
-./scripts/test_publish.sh
-```
-
-### Lint
-```bash
-# 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 v2.3.1 with 62 enabled linters. Always run linting locally before pushing to avoid CI failures.
-
-## Architecture Overview
-
-The codebase follows a clean architecture pattern:
-
-### Core Layers
-- **API Layer** (`internal/api/`) - HTTP handlers and routing
-- **Service Layer** (`internal/service/`) - Business logic implementation  
-- **Database Layer** (`internal/database/`) - Data persistence abstraction with MongoDB and in-memory implementations
-- **Domain Models** (`internal/model/`) - Core data structures
-- **Authentication** (`internal/auth/`) - GitHub OAuth integration
-
-### Request Flow
-1. HTTP requests enter through router (`internal/api/router/`)
-2. Handlers in `internal/api/handlers/v0/` validate and process requests
-3. Service layer executes business logic
-4. Database interface handles persistence
-5. JSON responses returned to clients
-
-### Key Interfaces
-- **Database Interface** (`internal/database/database.go`) - Abstracts data persistence with MongoDB and memory implementations
-- **RegistryService** (`internal/service/service.go`) - Business logic abstraction over database
-- **Auth Service** (`internal/auth/auth.go`) - GitHub OAuth token validation
-
-### Authentication Flow
-Publishing requires GitHub OAuth validation:
-1. Extract bearer token from Authorization header
-2. Validate token with GitHub API
-3. Verify repository ownership matches token owner
-4. Check organization membership if applicable
-
-### Design Patterns
-- **Factory Pattern** for service creation with dependency injection
-- **Repository Pattern** for database abstraction
-- **Context Pattern** for timeout management (5-second DB operations)
-- **Cursor-based Pagination** using UUIDs for stateless pagination
-
-## Environment Variables
-Key configuration for development:
-- `MCP_REGISTRY_DATABASE_URL` (default: `mongodb://localhost:27017`)
-- `MCP_REGISTRY_GITHUB_CLIENT_ID` 
-- `MCP_REGISTRY_GITHUB_CLIENT_SECRET`
-- `MCP_REGISTRY_LOG_LEVEL` (default: `info`)
-- `MCP_REGISTRY_SERVER_ADDRESS` (default: `:8080`)
-- `MCP_REGISTRY_SEED_IMPORT` (default: `true`)
-- `MCP_REGISTRY_SEED_FILE_PATH` (default: `data/seed.json`)
+Import @README.md

CONTRIBUTING.md

@@ -4,7 +4,15 @@ A community driven registry service for Model Context Protocol (MCP) servers.
 
 ## Development Status
 
-This project is being built in the open and is currently in the early stages of development. Please see the [overview discussion](https://github.com/modelcontextprotocol/registry/discussions/11) for the project scope and goals. If you would like to contribute, please check out the [contributing guidelines](CONTRIBUTING.md).
+This project is being built in the open and is currently in the early stages of development. Please see the [overview discussion](https://github.com/modelcontextprotocol/registry/discussions/11) for the project scope and goals.
+
+### Contributing
+
+Use [Discussions](https://github.com/modelcontextprotocol/registry/discussions) to propose and discuss product and/or technical **requirements**.
+
+Use [Issues](https://github.com/modelcontextprotocol/registry/issues) to track **well-scoped technical work** that the community agrees should be done at some point.
+
+Open [Pull Requests](https://github.com/modelcontextprotocol/registry/pulls) when you want to **contribute work towards an Issue**, or you feel confident that your contribution is desireable and small enough to forego community discussion at the requirements and planning levels.
 
 ## Overview
 
@@ -43,19 +51,32 @@ The easiest way to get the registry running is uses docker compose. This will se
 make dev-compose
 ```
 
-This will start the MCP Registry service and MongoDB with Docker, exposing it on port 8080.
+This will start the MCP Registry service and MongoDB with Docker, running at [`localhost:8080`](http://localhost:8080).
 
 ## Building
 
-If you prefer to run the service locally without Docker, you can build and run it directly using Go.
+If you prefer to run the service locally without Docker, you can build and run it directly:
 
 ```bash
 # Build a registry executable
 make build
 ```
 This will create the `registry` binary in the current directory. You'll need to have MongoDB running locally or with Docker.
 
-By default, the service will run on `http://localhost:8080`.
+To run the service locally:
+```bash
+# Run registry locally (requires MongoDB)
+make dev-local
+```
+
+By default, the service will run on [`localhost:8080`](http://localhost:8080).
+
+To build the CLI tool for publishing MCP servers to the registry:
+
+```bash
+# Build the publisher tool
+make publisher
+```
 
 ## Development
 
@@ -70,14 +91,14 @@ make help
 Key development commands:
 
 ```bash
-# Build targets
-make build          # Build the registry application
-make publisher      # Build the publisher tool
-
 # Development
 make dev-compose   # Start development environment with Docker Compose
 make dev-local     # Run registry locally (requires MongoDB)
 
+# Build targets
+make build          # Build the registry application
+make publisher      # Build the publisher tool
+
 # Testing
 make test-unit        # Run unit tests with coverage report
 make test-integration # Run integration tests
@@ -123,35 +144,62 @@ git config core.hooksPath .githooks
 
 This will prevent commits that fail linting or have formatting issues.
 
-## Project Structure
+### Project Structure
 
 ```
 ├── api/           # OpenApi specification
 ├── cmd/           # Application entry points
 ├── config/        # Configuration files
 ├── internal/      # Private application code
-│   ├── api/       # HTTP server and request handlers
+│   ├── api/       # HTTP server and request handlers (routing)
+│   ├── auth/      # GitHub OAuth integration
 │   ├── config/    # Configuration management
-│   ├── model/     # Data models
-│   └── service/   # Business logic
+│   ├── database/  # Data persistence abstraction (MongoDB and in-memory)
+│   ├── model/     # Data models and domain structures
+│   └── service/   # Business logic implementation
 ├── pkg/           # Public libraries
 ├── scripts/       # Utility scripts
 └── tools/         # Command line tools
     └── publisher/ # Tool to publish MCP servers to the registry
 ```
 
-## API Documentation
+### Architecture Overview
 
-The API is documented using Swagger/OpenAPI. You can access the interactive Swagger UI at:
+### Request Flow
+1. HTTP requests enter through router (`internal/api/router/`)
+2. Handlers in `internal/api/handlers/v0/` validate and process requests
+3. Service layer executes business logic
+4. Database interface handles persistence
+5. JSON responses returned to clients
 
-```
-/v0/swagger/index.html
-```
+### Key Interfaces
+- **Database Interface** (`internal/database/database.go`) - Abstracts data persistence with MongoDB and memory implementations
+- **RegistryService** (`internal/service/service.go`) - Business logic abstraction over database
+- **Auth Service** (`internal/auth/auth.go`) - GitHub OAuth token validation
+
+### Authentication Flow
+Publishing requires GitHub OAuth validation:
+1. Extract bearer token from Authorization header
+2. Validate token with GitHub API
+3. Verify repository ownership matches token owner
+4. Check organization membership if applicable
 
-This provides a complete reference of all endpoints with request/response schemas and allows you to test the API directly from your browser.
+### Design Patterns
+- **Factory Pattern** for service creation with dependency injection
+- **Repository Pattern** for database abstraction
+- **Context Pattern** for timeout management (5-second DB operations)
+- **Cursor-based Pagination** using UUIDs for stateless pagination
 
 ## API Endpoints
 
+### API Documentation
+
+```
+GET /v0/swagger/index.html
+```
+
+The API is documented using Swagger/OpenAPI. This page provides a complete reference of all endpoints with request/response schemas and allows you to test the API directly from your browser.
+
 ### Health Check
 
 ```
@@ -369,71 +417,6 @@ The service can be configured using environment variables:
 | `MCP_REGISTRY_SEED_IMPORT`           | Import `seed.json` on first run | `true` |
 | `MCP_REGISTRY_SERVER_ADDRESS`        | Listen address for the server | `:8080` |
 
-
-## Testing
-
-### Unit Tests
-
-```bash
-# Run unit tests with coverage
-make test
-
-# Generate coverage report
-make coverage
-```
-
-### Integration Tests
-
-```bash
-# Run integration tests
-make integration-test
-```
-
-### API Endpoint Testing
-
-```bash
-# Test API endpoints (requires running server)
-make test-endpoints
-```
-
-You can also run the script directly with specific endpoints:
-
-```bash
-./scripts/test_endpoints.sh --endpoint health
-./scripts/test_endpoints.sh --endpoint servers
-```
-
-### Publish Endpoint Testing
-
-```bash
-# Test publish endpoint (requires BEARER_TOKEN env var)
-make test-publish
-```
-
-### Validation
-
-```bash
-# Validate JSON schemas
-make validate-schemas
-
-# Validate examples against schemas
-make validate-examples
-
-# Run all validation checks
-make validate
-```
-
-### Comprehensive Testing
-
-```bash
-# Run all checks (lint, validate, test)
-make check
-```
-
 ## License
 
 See the [LICENSE](LICENSE) file for details.
-
-## Contributing
-
-See the [CONTRIBUTING](CONTRIBUTING.md) file for details.