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
|
# 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.
|
Import @README.md
|
||||||
|
|
||||||
## 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`)
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
## 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
|
## Overview
|
||||||
|
|
||||||
|
|
@ -43,11 +51,11 @@ The easiest way to get the registry running is uses docker compose. This will se
|
||||||
make dev-compose
|
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
|
## 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
|
```bash
|
||||||
# Build a registry executable
|
# 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.
|
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
|
## Development
|
||||||
|
|
||||||
|
|
@ -70,14 +91,14 @@ make help
|
||||||
Key development commands:
|
Key development commands:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Build targets
|
|
||||||
make build # Build the registry application
|
|
||||||
make publisher # Build the publisher tool
|
|
||||||
|
|
||||||
# Development
|
# Development
|
||||||
make dev-compose # Start development environment with Docker Compose
|
make dev-compose # Start development environment with Docker Compose
|
||||||
make dev-local # Run registry locally (requires MongoDB)
|
make dev-local # Run registry locally (requires MongoDB)
|
||||||
|
|
||||||
|
# Build targets
|
||||||
|
make build # Build the registry application
|
||||||
|
make publisher # Build the publisher tool
|
||||||
|
|
||||||
# Testing
|
# Testing
|
||||||
make test-unit # Run unit tests with coverage report
|
make test-unit # Run unit tests with coverage report
|
||||||
make test-integration # Run integration tests
|
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.
|
This will prevent commits that fail linting or have formatting issues.
|
||||||
|
|
||||||
## Project Structure
|
### Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
├── api/ # OpenApi specification
|
├── api/ # OpenApi specification
|
||||||
├── cmd/ # Application entry points
|
├── cmd/ # Application entry points
|
||||||
├── config/ # Configuration files
|
├── config/ # Configuration files
|
||||||
├── internal/ # Private application code
|
├── internal/ # Private application code
|
||||||
│ ├── api/ # HTTP server and request handlers
|
│ ├── api/ # HTTP server and request handlers (routing)
|
||||||
|
│ ├── auth/ # GitHub OAuth integration
|
||||||
│ ├── config/ # Configuration management
|
│ ├── config/ # Configuration management
|
||||||
│ ├── model/ # Data models
|
│ ├── database/ # Data persistence abstraction (MongoDB and in-memory)
|
||||||
│ └── service/ # Business logic
|
│ ├── model/ # Data models and domain structures
|
||||||
|
│ └── service/ # Business logic implementation
|
||||||
├── pkg/ # Public libraries
|
├── pkg/ # Public libraries
|
||||||
├── scripts/ # Utility scripts
|
├── scripts/ # Utility scripts
|
||||||
└── tools/ # Command line tools
|
└── tools/ # Command line tools
|
||||||
└── publisher/ # Tool to publish MCP servers to the registry
|
└── 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
|
||||||
|
|
||||||
```
|
### Key Interfaces
|
||||||
/v0/swagger/index.html
|
- **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 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
|
### 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_SEED_IMPORT` | Import `seed.json` on first run | `true` |
|
||||||
| `MCP_REGISTRY_SERVER_ADDRESS` | Listen address for the server | `:8080` |
|
| `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
|
## License
|
||||||
|
|
||||||
See the [LICENSE](LICENSE) file for details.
|
See the [LICENSE](LICENSE) file for details.
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
See the [CONTRIBUTING](CONTRIBUTING.md) file for details.
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue