Open Proto

An MCP-native architectural retrieval and synthesis engine for AI coding agents.

What is Open Proto?

Open Proto bridges the gap between a software idea and a production-grade architectural foundation. Instead of hallucinating architecture, your AI coding agent searches GitHub for proven, permissively-licensed open-source projects that already solved similar problems — then synthesizes structured blueprints, security reports, design recommendations, and health audits you can build on.

Think of it as a research librarian for AI agents: it doesn't write your code, but it makes sure you're building on proven ground.

No LLM inference inside. All retrieval, scoring, and synthesis is deterministic. The host AI handles all reasoning and judgment calls.

Features

Feature	Description
🔍 Deterministic Retrieval	Searches GitHub with domain-specific queries, license filters, and adaptive star scoring. No black-box LLM calls.
🛡️ License Validation	Hard filter for MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause. GPL and proprietary licenses are rejected automatically.
⚡ Concurrent Rust Engine	High-performance GitHub API retrieval via PyO3 bindings. Auto-rotates multiple tokens on rate limits.
📐 Blueprint Synthesis	Generates architecture overviews, integration strategies, and builder context from real repos.
🎨 Visual Design Reports	Extracts color palettes, component patterns, and animation recipes from design-heavy reference repos.
🔒 Security Reviews	Domain-specific and stack-specific risk mapping with actionable OWASP-style checklists.
🏥 Health Audits	Checks referenced repos for staleness, abandonment, and archival status.
🔄 Lifecycle-Aware	Projects persist across sessions. Evolve, secure, beautify, and audit them incrementally.

How It Works

┌─────────────────────────────────────────────────────────────────────────┐
│  PHASE 0 — Initial Discovery (first time only)                          │
│    1. decompose_prompt(user_prompt)    → YOU fill the schema            │
│    2. find_prototype_foundation(schema) → repos + blueprints            │
│    3. initialize_project(schema, result) → SAVE project_id!             │
├─────────────────────────────────────────────────────────────────────────┤
│  PHASE 1+ — Enhancement & Iteration (repeat as needed)                  │
│    4. evolve_prototype(project_id, "Add feature X")                     │
├─────────────────────────────────────────────────────────────────────────┤
│  PHASE 5 — Visual Polish                                                │
│    5. beautify_prototype(project_id) → design report                    │
├─────────────────────────────────────────────────────────────────────────┤
│  PHASE 6 — Security Review (before shipping)                            │
│    6. security_review(project_id) → security report + checklist         │
├─────────────────────────────────────────────────────────────────────────┤
│  PHASE X — Maintenance (periodic)                                       │
│    7. audit_project(project_id) → health report                         │
└─────────────────────────────────────────────────────────────────────────┘

Sample Output

After running find_prototype_foundation, Open Proto returns three blueprint documents. Here's what they look like for a real request — "Build an e-commerce platform with product catalog, shopping cart, and payment processing in Python."

📐 architecture.md — Repository mapping & service boundaries

# Architecture Overview

The following open-source repositories have been selected as architectural foundations:

| Role | Repository | License | Language | Frameworks | Patterns |
|------|------------|---------|----------|------------|----------|
| Backend | [saleor/saleor](https://github.com/saleor/saleor) | BSD-3 | Python | Django, Graphene | Modular Monolith, GraphQL API |
| Backend | [medusajs/medusa](https://github.com/medusajs/medusa) | MIT | TypeScript | Express, TypeORM | Plugin Architecture, API / REST |
| Frontend | [vuestorefront/vue-storefront](https://github.com/vuestorefront/vue-storefront) | MIT | TypeScript | Vue, Nuxt | Component-Based Frontend, SSR |
| Catalog | [meilisearch/meilisearch](https://github.com/meilisearch/meilisearch) | MIT | Rust | Actix-web | Search-First Indexing |
| Payments | [stripe/stripe-python](https://github.com/stripe/stripe-python) | MIT | Python | — | SDK / Wrapper |

## Service Boundaries

- **saleor/saleor** — Core commerce engine: products, orders, users, inventory.
- **medusajs/medusa** — Reference for cart logic, payment orchestration, and plugin system.
- **vuestorefront/vue-storefront** — Frontend architecture: PDP, PLP, checkout flow, PWA patterns.
- **meilisearch/meilisearch** — Product search & filtering (faceted navigation, typo-tolerance).
- **stripe/stripe-python** — Payment intent flow, webhook handling, refund logic.

## Recommended Tech Stack

Since no tech stack was specified, Open Proto recommends the following based on matched repositories:

- **Runtime:** Python 3.11+
- **Frameworks:** FastAPI (API), SQLAlchemy (ORM), Celery (background jobs)
- **Search:** Meilisearch or Elasticsearch for product catalog
- **Payments:** Stripe Python SDK
- **Frontend:** React or Vue SPA with SSR

## What Is Not Covered

- **inventory-management** — no repository coverage found. Saleor has basic stock tracking but multi-warehouse logic must be built from scratch.
- **shipping-rates** — no repository coverage found. Integrate a third-party provider (Shippo, EasyPost).

🔌 integration_strategy.md — How to study and adapt each repo

# Integration Strategy

## Recommended Integration Order

1. **saleor/saleor** — [https://github.com/saleor/saleor](https://github.com/saleor/saleor)
   - Role: Backend
   - Why selected: Most comprehensive Python commerce backend. Covers 80% of required pillars.
   - Dependency manifest: `pyproject.toml` (Poetry)
   - Entry points: `saleor/graphql/api.py`, `saleor/product/models.py`, `saleor/checkout`
   - Architectural patterns: Modular Monolith, GraphQL API

2. **medusajs/medusa** — [https://github.com/medusajs/medusa](https://github.com/medusajs/medusa)
   - Role: Backend
   - Why selected: Excellent reference for cart state machine and payment-provider abstraction.
   - Dependency manifest: `package.json`, `yarn.lock`
   - Entry points: `packages/medusa/src/api`, `packages/core-flows`
   - Architectural patterns: Plugin Architecture, API / REST

3. **vuestorefront/vue-storefront** — [https://github.com/vuestorefront/vue-storefront](https://github.com/vuestorefront/vue-storefront)
   - Role: Frontend
   - Why selected: Production-grade storefront with composable architecture.
   - Entry points: `packages/theme/pages`, `packages/sdk`
   - Architectural patterns: Component-Based Frontend, SSR

## Concrete Implementation Guidance

### saleor/saleor
- Use **Modular Monolith** as the overall architecture.
- Key dependencies to reference: Django, Graphene, Pillow, Stripe
- Start reading from: `saleor/product/models.py` → understand the variant/attribute system.
- Adapt the GraphQL schema design for your own API layer (or switch to REST if preferred).

### medusajs/medusa
- Use **Plugin Architecture** as the reference for extending core logic.
- Key dependencies to reference: Express, TypeORM, awilix (DI container)
- Start reading from: `packages/medusa/src/services/cart.ts` → understand the cart state machine.
- Do NOT import Medusa directly. Re-implement the cart/payment orchestration patterns in Python.

## Dependency Conflicts & Warnings

- **saleor/saleor** uses Django + Graphene. If you choose FastAPI, you cannot reuse Django models directly. Study the domain logic, then re-implement with SQLAlchemy + Pydantic.
- **medusajs/medusa** is Node.js/TypeScript. It is a pattern reference only — no code can be imported into a Python project.

🛠️ builder_context.md — Your implementation roadmap

# Builder Context

## Prioritized Implementation Tasks

- [ ] Evaluate **saleor/saleor** (Backend) — study product/catalog domain model
- [ ] Evaluate **medusajs/medusa** (Backend) — study cart & payment orchestration
- [ ] Evaluate **vuestorefront/vue-storefront** (Frontend) — study PDP/PLP component patterns
- [ ] Evaluate **meilisearch/meilisearch** (Catalog) — study indexing & faceted search
- [ ] Set up project skeleton with FastAPI + SQLAlchemy + Alembic
- [ ] Implement Product / Variant / Attribute models (inspired by Saleor)
- [ ] Implement Cart state machine with session + DB persistence (inspired by Medusa)
- [ ] Integrate Stripe payment intents & webhook handlers
- [ ] Build product search endpoint with Meilisearch client
- [ ] Scaffold React/Vue frontend with route structure matching Vue Storefront

## File Structure to Create

Based on matched repositories, create the following structure:

src/ api/ # FastAPI routers (products, cart, orders, checkout) models/ # SQLAlchemy ORM models schemas/ # Pydantic request/response models services/ # Business logic (cart, payment, inventory) plugins/ # Payment provider abstractions (Stripe, PayPal) search/ # Meilisearch indexing & query builders tasks/ # Celery background jobs (order emails, stock alerts) tests/ unit/ # Service-layer tests integration/ # API endpoint tests frontend/ components/ # Reusable UI (ProductCard, CartDrawer, FilterSidebar) pages/ # Route-level views hooks/ # Data fetching & cart state hooks store/ # Global state (Zustand / Pinia / Redux)


## Architectural Warnings

- ⚠️ Saleor's GraphQL schema is large and opinionated. If you switch to REST, you lose the precise field-selection benefit — plan your DTOs carefully.
- ⚠️ Medusa's plugin system relies on Node.js module resolution. In Python, use a registry-pattern or entry-point-based plugin loader instead.

## Gaps

- **inventory-management** — must be built from scratch. Design a stock-movement ledger (FIFO approach recommended).
- **shipping-rates** — must be built from scratch. Abstract behind a `ShippingProvider` interface.
- **admin-dashboard** — no repository coverage found. Consider using an existing headless CMS or building a simple internal tool.

## Build from Scratch vs. Adapt

Repositories marked above should be **studied and adapted**, not imported as dependencies. The host AI should:
1. Understand the architectural patterns used
2. Re-implement the relevant parts in the target stack
3. Disregard any parts that conflict with the target architecture

These documents are synthesized from real GitHub repositories with verified MIT/Apache/BSD licenses. No LLM hallucination. Every repo link is real and every pattern is extracted from actual code.

Tech Stack

Layer	Technology
MCP Server	FastMCP (Python)
Orchestration	Python 3.10+ · Pydantic · httpx · structlog
Retrieval Engine	Rust 1.70+ · tokio · reqwest · serde · rayon
Bridge	PyO3 0.28 + maturin
Testing	pytest · pytest-asyncio
Packaging	hatchling

Quick Start

Prerequisites

Python 3.10+
Rust toolchain (for building the retrieval engine)
GitHub Personal Access Token with public_repo scope

Install

# Clone the repository
git clone https://github.com/GrimNej/open-proto.git
cd open-proto

# Create .env from example
cp .env.example .env
# Edit .env and add your GITHUB_TOKEN

# Install Python dependencies
pip install -e ".[dev]"

# Build Rust engine
pip install maturin
bash scripts/build_rust.sh

Run

python -m apps.mcp_server.server

MCP Client Integration

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "open-proto": {
      "command": "python",
      "args": ["-m", "apps.mcp_server.server"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
        "GITHUB_TOKEN_1": "${GITHUB_TOKEN_1}",
        "GITHUB_TOKEN_2": "${GITHUB_TOKEN_2}"
      }
    }
  }
}

Kimi Code

Add to ~/.kimi/mcp.json:

{
  "mcpServers": {
    "open-proto": {
      "command": "python",
      "args": ["-m", "apps.mcp_server.server"],
      "cwd": "/path/to/open-proto",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "PYTHONPATH": "/path/to/open-proto"
      }
    }
  }
}

Tip: Use the full absolute path to your Python executable if python resolves to the wrong installation.

Docker

docker-compose up --build

Environment Variables

Variable	Required	Default	Description
`GITHUB_TOKEN`	Yes	—	Primary GitHub Personal Access Token
`GITHUB_TOKEN_1`	No	—	Secondary token (auto-rotation fallback)
`GITHUB_TOKEN_2`	No	—	Tertiary token (auto-rotation fallback)
`GITHUB_MAX_CONCURRENT_REQUESTS`	No	`5`	Concurrent Rust fetcher threads
`MAX_SEARCH_RESULTS_PER_QUERY`	No	`20`	Results per license-specific query
`LOG_LEVEL`	No	`INFO`	Logging level

Each token provides 5,000 search requests/hour. With 3 tokens, effective capacity is 15,000/hour.

Testing

# Unit tests (no network required)
pytest tests/unit/

# Integration tests (requires GITHUB_TOKEN)
pytest tests/integration/

# All tests
pytest tests/

File Structure

open-proto/
├── apps/
│   └── mcp_server/
│       ├── server.py              # FastMCP entrypoint
│       └── tools/
│           ├── decompose.py       # Phase 0: Schema template
│           ├── find.py            # Phase 0: GitHub search + synthesis
│           ├── initialize.py      # Phase 0: State persistence
│           ├── evolve.py          # Phase 1+: Feature evolution
│           ├── beautify.py        # Phase 5: Visual design research
│           ├── security.py        # Phase 6: Security review
│           └── audit.py           # Phase X: Health audit
├── core/
│   ├── decomposition/             # Prompt schema definitions
│   ├── intelligence/              # GitHub bridge, token manager, query builder
│   ├── scoring/                   # Relevance scoring algorithms
│   ├── synthesis/                 # Blueprint & report generation
│   ├── design/                    # Visual design extraction & diff generation
│   ├── security/                  # Security risk synthesizer
│   ├── observations/              # Compatibility warnings
│   ├── lifecycle/                 # Project state persistence
│   └── blueprints/                # Blueprint generators
├── rust_engine/                   # Rust retrieval engine (PyO3)
│   └── src/
│       ├── github/                # Search, metadata, rate limiting
│       └── parsers/               # License, dependency, README parsing
├── tests/
│   ├── unit/                      # Deterministic logic tests
│   └── integration/               # End-to-end MCP tool tests
├── docker/
│   └── Dockerfile.mcp             # Container build
├── schemas/                       # JSON schemas for I/O validation
├── scripts/
│   ├── build_rust.sh              # Rust engine build script
│   └── setup_env.sh               # Environment setup
├── AGENTS.md                      # 📖 Agent usage guide (read this!)
├── docs/mcp_integration.md        # 🔌 MCP client configuration reference
└── README.md                      # ← You are here

Documentation

Document	What's Inside
AGENTS.md	Start here. Complete agent usage guide: all 8 tools, workflows, best practices, error handling, and the visual design artistic contract.
docs/mcp_integration.md	MCP client configuration (Claude, Kimi, generic), token management, state persistence, architecture diagram, troubleshooting.
BluePrint.md	Master blueprint: project philosophy, decomposition ownership, technology stack, design principles.

The 8 MCP Tools

Tool	Phase	Description
`decompose_prompt`	0	Returns an empty schema — you fill it with functional pillars and tech preferences.
`find_prototype_foundation`	0	Searches GitHub, scores repos, synthesizes architecture blueprints.
`initialize_project`	0	Persists discovery results. Never skip. Returns a `project_id` you must save.
`evolve_prototype`	1+	Finds repos for adding new features to an existing project.
`beautify_prototype`	5	Researches visual design references — colors, components, animations, layout.
`security_review`	6	Maps domain-specific and stack-specific security risks with checklists.
`audit_project`	X	Checks repo health (staleness, abandonment, archival).
`list_projects`	—	Utility to recover lost project IDs.

For detailed schemas, input/output examples, and workflow guidance, see AGENTS.md.

Contributing

Fork the repo
Create a feature branch (git checkout -b feature/amazing-thing)
Commit your changes (git commit -am 'Add amazing thing')
Push to the branch (git push origin feature/amazing-thing)
Open a Pull Request

Please read AGENTS.md for architecture context and BluePrint.md for design philosophy before making changes.

License

MIT — see the repository for full license text.

Built for agents, by builders.

Navigation Menu

Repository navigation

About

Repository files navigation

Open Proto

What is Open Proto?

Features

How It Works

Sample Output

Tech Stack

Quick Start

Prerequisites

Install

Run

MCP Client Integration

Claude Code

Kimi Code

Docker

Environment Variables

Testing

File Structure

Documentation

The 8 MCP Tools

Contributing

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
apps		apps
assets		assets
core		core
docker		docker
docs		docs
rust_engine		rust_engine
schemas		schemas
scripts		scripts
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

Open Proto

What is Open Proto?

Features

How It Works

Sample Output

Tech Stack

Quick Start

Prerequisites

Install

Run

MCP Client Integration

Claude Code

Kimi Code

Docker

Environment Variables

Testing

File Structure

Documentation

The 8 MCP Tools

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages