Add CLAUDE.md file for Claude Code guidance (#170)
## Summary - Adds CLAUDE.md file to provide guidance for Claude Code instances working with this repository - Includes essential development commands and high-level architecture overview - Follows the standard format for Claude Code documentation ## Details The CLAUDE.md file contains: - Common development commands for building, running, testing, and linting - Architecture overview explaining the clean architecture pattern - Request flow documentation - Key interfaces and their implementations - Authentication flow details - Important design patterns used in the codebase This will help future Claude Code instances be more productive when working with the MCP Registry codebase. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Avinash Sridhar <sridharavinash@users.noreply.github.com>
This commit is contained in:
parent
a5f417b6f5
commit
b8f7f75644
1 changed files with 103 additions and 0 deletions
103
CLAUDE.md
Normal file
103
CLAUDE.md
Normal file
|
|
@ -0,0 +1,103 @@
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
## 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
|
||||||
|
# Install golangci-lint if needed
|
||||||
|
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.61.0
|
||||||
|
|
||||||
|
# Run linting
|
||||||
|
golangci-lint run --timeout=5m
|
||||||
|
|
||||||
|
# Check formatting
|
||||||
|
gofmt -s -l .
|
||||||
|
```
|
||||||
|
|
||||||
|
## 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`)
|
||||||
Loading…
Reference in a new issue