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 <noreply@anthropic.com>
This commit is contained in:
adam jones 2025-08-06 16:05:07 +01:00 • committed by GitHub
commit 431a670f1b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

121
CLAUDE.md
View file

@ -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