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
3 changed files with 68 additions and 209 deletions

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

View file

@ -1,7 +0,0 @@
# 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.

149
README.md
View file

@ -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,11 +51,11 @@ 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
@ -55,7 +63,20 @@ 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
This provides a complete reference of all endpoints with request/response schemas and allows you to test the API directly from your browser.
### 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
## 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.