Skip to content

DEV_INSTRUCTIONS.md

Latest commit

 

History

History
148 lines (110 loc) · 4.82 KB

DEV_INSTRUCTIONS.md

File metadata and controls

148 lines (110 loc) · 4.82 KB
Raw

Getting Started

Prerequisite Reading

READ THIS FIRST: CONTRIBUTING.md

Before you start contributing, please review the project's contribution guidelines.

Then read the Theory of the System — the causal design narrative and the core invariants (control-plane/data-plane split, generic reverse-proxy gateway, A2A peer-to-peer, config parity, fail-closed admission, and more). A change that breaks an invariant without arguing for it will be flagged in review, so understand them before you design.

Setup Instructions for Contributors

Step 1: Choose Your Development Environment

We recommend the fastest option to get started:

Option A: macOS Setup (Fastest ⚡)

Complete this setup guide first:

Option B: EC2 Complete Configuration (Preferred for Server Setup)

If working on EC2 or a Linux server, complete this guide first:

Before You Start Coding

1. Ask Your Coding Assistant to Read Documentation

Before making any code changes, ask your AI coding assistant to read:

LLM/AI Documentation (Critical for understanding the project):

Coding Standards and Guidelines:

  • CLAUDE.md - Project-specific coding standards

2. Review the CLAUDE.md File

This project uses CLAUDE.md for coding standards. The file is already included in the repository root - make sure to review it before contributing.

Testing Your Changes

Before submitting a pull request, you must run and pass the test suite:

Quick Start Testing

# Generate fresh credentials (tokens expire in 5 minutes)
./credentials-provider/generate_creds.sh

# Run tests locally (skip production for fast iteration)
./tests/run_all_tests.sh --skip-production

For PR Merge (REQUIRED)

# Full test suite including production tests
./tests/run_all_tests.sh

# All tests must pass (0 failures) before merging

Understanding the Tests

See the comprehensive testing documentation:

Common Testing Workflows

Agent CRUD Testing:

./credentials-provider/generate_creds.sh
bash tests/agent_crud_test.sh

Access Control Testing (LOB Bots):

./keycloak/setup/generate-agent-token.sh admin-bot
./keycloak/setup/generate-agent-token.sh lob1-bot
./keycloak/setup/generate-agent-token.sh lob2-bot
bash tests/run-lob-bot-tests.sh

Check Test Logs:

ls -lh /tmp/*_*.log
grep -i "error\|fail" /tmp/*.log

Fork and Contribute

Repository Access

Important: There is no direct access to this repository. To contribute:

  1. Fork the repository on GitHub

    https://github.com/agentic-community/mcp-gateway-registry

  2. Clone your fork locally

    git clone https://github.com/YOUR-USERNAME/mcp-gateway-registry.git
cd mcp-gateway-registry

  3. Create a feature branch

    git checkout -b feat/your-feature-name

  4. Make your changes following the coding standards in CLAUDE.md

  5. Commit and push to your fork

    git push origin feat/your-feature-name

  6. Create a Pull Request to the main repository

    • Use a clear, descriptive PR title
    • Reference any related issues
    • Include test results and screenshots if applicable

Development Checklist

Before submitting a pull request:

  • Completed one of the setup guides (macOS or EC2)
  • Read docs/llms.txt
  • Read CLAUDE.md (coding standards)
  • Code follows project conventions (use ruff, mypy, pytest)
  • Generated fresh credentials: ./credentials-provider/generate_creds.sh
  • Local tests pass: ./tests/run_all_tests.sh --skip-production
  • PR merge tests pass: ./tests/run_all_tests.sh (all tests must pass)
  • Reviewed test documentation: tests/README.md
  • Changes are pushed to a fork, not directly to this repo
  • Pull request is created with clear description

Questions?

  • Check the CONTRIBUTING.md file for more details
  • Review existing PRs to see contribution patterns
  • Ask your coding assistant to review the documentation with you

Happy coding! 🚀