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:
parent
f5bf542697
commit
431a670f1b
3 changed files with 68 additions and 209 deletions
121
CLAUDE.md
121
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`)
|
||||
Import @README.md
|
||||
|
|
|
|||
|
|
@ -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
149
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue