4e221e49a8## Summary This PR improves the developer experience by adding clear linting documentation and optional pre-commit hooks to catch issues before CI. Helpful to avoid fighting Claude Code / Copilot on "please make sure linting passes CI". ## Changes - Updated `README.md` with: - Go 1.23.x requirement (was "1.18 or later") - golangci-lint v1.61.0 in prerequisites - New Development section with linting instructions - Updated `CLAUDE.md` with: - Development Setup section - Added `.githooks/pre-commit`: - Runs golangci-lint and gofmt checks - References README for installation instructions - Can be bypassed with `--no-verify` when needed ## Test Plan - [x] Verified pre-commit hook blocks commits when golangci-lint is missing - [x] Confirmed hook shows clear error message pointing to README - [x] Tested that linting passes with Go 1.23.0 and golangci-lint v1.61.0 - [x] Verified gofmt correctly identifies formatting issues Co-authored w/ Claude Code --------- Co-authored-by: Charles Lowell <10964656+chlowell@users.noreply.github.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 v1.61.0** - Install with:
|
|
```bash
|
|
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.61.0
|
|
```
|
|
|
|
### 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
|
|
./integrationtests/run_tests.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 v1.61.0 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`) |