6ba612942eMigrate golangci-lint from v1 to v2. ## Motivation and Context The golangci-lint has been upgraded to v2 since March 2025. The v2 of golangci-lint has simplified the linters management. ## How Has This Been Tested? Tested locally with golangci-lint@v2.1.6 ## Breaking Changes No. ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update ## Checklist <!-- Go over all the following points, and put an `x` in all the boxes that apply. --> - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [ ] I have added or updated documentation as needed ## Additional context <!-- Add any other context, implementation notes, or design decisions --> --------- Co-authored-by: haokunt <haokunt@opera.com> Co-authored-by: Avinash Sridhar <sridharavinash@users.noreply.github.com> Co-authored-by: Adam Jones <adamj+git@anthropic.com>
121 lines
No EOL
3.7 KiB
Markdown
121 lines
No EOL
3.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
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`) |