diff --git a/CLAUDE.md b/CLAUDE.md index 6e2143f..213802b 100644 --- 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`) \ No newline at end of file +Import @README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 2141a51..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/README.md b/README.md index b25f539..50d6426 100644 --- 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 @@ -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.