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:
adam jones
GitHub
parent
f5bf542697
commit
431a670f1b
1 changed files with 68 additions and 209 deletions
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