refactor: consolidate documentation and remove redundancy

domdomegg · domdomegg · commit 38538b59b258 · 2025-08-06T12:26:14.000+01:00
- Remove CLAUDE.md with Import statement in favor of direct README.md reference
- Consolidate CONTRIBUTING.md content into README.md Contributing section
- Move architecture details and useful developer info from old CLAUDE.md to README.md
- Remove redundant information that was duplicated between files

This reduces documentation maintenance overhead by having a single source of truth
in README.md while keeping Claude Code functional.
diff --git a/CLAUDE.md b/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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.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
 
@@ -55,8 +63,21 @@ go build ./cmd/registry
 ```
 This will create the `registry` binary in the current directory. You'll need to have MongoDB running locally or with Docker.
 
+You can also run the service directly:
+```bash
+# Direct execution
+go run cmd/registry/main.go
+```
+
 By default, the service will run on `http://localhost:8080`.
 
+There is also a CLI tool to publish MCP servers to the registry. You can build it with:
+
+```bash
+# Build the publisher tool
+cd tools/publisher && ./build.sh
+```
+
 ## Development
 
 ### Linting
@@ -84,34 +105,61 @@ 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
+
+### 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
 
-The API is documented using Swagger/OpenAPI. You can access the interactive Swagger UI at:
+## API Endpoints
+
+### API Documentation
 
 ```
-/v0/swagger/index.html
+GET /v0/swagger/index.html
 ```
 
-This provides a complete reference of all endpoints with request/response schemas and allows you to test the API directly from your browser.
-
-## API Endpoints
+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
 
@@ -333,6 +381,22 @@ The service can be configured using environment variables:
 
 ## Testing
 
+### Unit Tests
+
+```bash
+# Run unit tests
+go test -v -race -coverprofile=coverage.out -covermode=atomic ./internal/...
+```
+
+### Integration Tests
+
+```bash
+# Run integration tests
+./tests/integration/run.sh
+```
+
+### API Endpoint Tests
+
 Run the test script to validate API endpoints:
 
 ```bash
@@ -346,10 +410,14 @@ You can specify specific endpoints to test:
 ./scripts/test_endpoints.sh --endpoint servers
 ```
 
-## License
+### Publish Endpoint Test
 
-See the [LICENSE](LICENSE) file for details.
+```bash
+# Test publish endpoint (requires GitHub token)
+export BEARER_TOKEN=your_github_token_here
+./scripts/test_publish.sh
+```
 
-## Contributing
+## License
 
-See the [CONTRIBUTING](CONTRIBUTING.md) file for details.
+See the [LICENSE](LICENSE) file for details.
