Developer Onboarding & Contributing

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• AGENTS.md
• CLAUDE.md
• package.json
• wrangler.toml
• scripts/setup-cf.js
• src/app.ts

e-zer0 is a self-hosted, AI-native bridge that connects AI agents to email accounts via the Model Context Protocol (MCP). It provides a secure infrastructure for agents to read, search, and manage emails while protecting sensitive user data through redaction and audit logging. Sources: README.md:1-12, AGENTS.md:5-9

Developers contribute to e-zer0 by improving email provider integrations, enhancing security features, or expanding the MCP toolset. The project runs on the Cloudflare Developer Platform, utilizing Workers, D1, and Vectorize to maintain a zero-trust architecture. Sources: CONTRIBUTING.md:1-10, AGENTS.md:11-18

Architecture Overview

The system architecture relies exclusively on Cloudflare services. It uses Hono as the web framework for both routing and server-side rendered (SSR) JSX components. Sources: AGENTS.md:11-18, AGENTS.md:65-70

Technology Stack

Component	Technology	Description
Compute	Cloudflare Workers	Serverless TypeScript environment (V8 isolates).
Framework	Hono	Handles routing, middleware, and JSX-based UI.
Database	Cloudflare D1	Relational SQLite database for users and settings.
Vector Store	Cloudflare Vectorize	Stores embeddings for semantic email search.
AI/ML	Workers AI	Generates embeddings using bge-base-en-v1.5.
MCP	MCP SDK	Implements Streamable HTTP Transport for agents.

Sources: AGENTS.md:11-18, wrangler.toml:1-40, package.json:44-48

System Data Flow

The following diagram illustrates how a request from an AI Agent flows through the system to an email provider.

Local Development Setup

To begin development, you must use Node.js 22 to match the project's CI environment. Sources: CONTRIBUTING.md:25-30

Initializing the Project

1. Clone the repository: `git clone https://github.com/nootn/e-zer0.git%60
2. Install dependencies: npm install
3. Configure local secrets:
   • Copy .dev.vars.example to .dev.vars.
   • Run npm run setup-cf to generate ENCRYPTION_KEY and JWT_SECRET.
4. Prepare the database: Run npm run db:migrate:local.
5. Start the server: Run npm run dev to launch the instance at http://localhost:8787.

Sources: README.md:231-248, CONTRIBUTING.md:38-45, scripts/setup-cf.js:15-60

Common Developer Commands

Command	Action
npm run check	Runs formatting, linting, and vitest suites.
npm run db:studio	Opens a local D1 database viewer.
npm run db:reset:local:unix	Wipes the local database and reapplies migrations.
npm run format	Formats code using Prettier.
npm run setup-cf	Provisions Cloudflare resources and generates local keys.

Sources: package.json:6-23, CLAUDE.md:6-18

Coding Standards

Environment Restrictions

The application runs on Cloudflare Workers V8 isolates, not Node.js. You must never use Node.js built-ins like fs, path, or process.env.

• Use crypto.subtle for cryptographic operations.
• Access bindings through the c.env object in Hono.
• Use Cloudflare D1 env.DB.prepare() for database queries.

Sources: AGENTS.md:37-45, CLAUDE.md:20-22

Security Requirements

Every tool execution through the MCP server must follow strict security protocols:

• Audit Logging: Every action must call logAudit in src/mcp/tools.ts.
• Sanitization: Email content must pass through sanitizeEmailContent() in src/lib/sanitizer.ts to redact PII and detect prompt injection.
• Secrets: Store provider tokens encrypted at rest using AES-256-GCM. Decrypt them only immediately before use.

Sources: AGENTS.md:47-57, src/app.ts:25-30

UI Development

The UI uses server-side rendered Hono JSX.

• Do not add client-side frameworks (React, Vue, etc.).
• Style using plain CSS in public/style.css with modern CSS variables.
• Use the Layout, Card, and Alert components found in src/views/layout.tsx.

Sources: AGENTS.md:59-63, src/views/layout.tsx:1-125

Contribution Workflow

1. Fork and Branch: Create a feature branch from a forked repository.
2. Implement Changes: Follow the coding standards and update relevant documentation in docs/.
3. Verify: Ensure npm run check passes. This gate checks formatting, TypeScript types, and runs tests.
4. Pull Request: Open a PR against the main branch. Provide screenshots for UI changes and describe the testing performed.

Sources: CONTRIBUTING.md:52-60, AGENTS.md:75-80

Directory Structure

• src/lib/email/: Provider-specific API clients (Gmail, Outlook).
• src/mcp/: MCP tool implementations and server setup.
• src/routes/: Hono route handlers for the web UI.
• src/views/: JSX components for server-side rendering.
• migrations/: D1 SQL schema changes.

Sources: AGENTS.md:20-30, CLAUDE.md:24-34

Security Policy

Report suspected vulnerabilities privately to the maintainer at the email address provided in SECURITY.md. Do not include real credentials or mailbox content in bug reports. Use synthetic data for reproduction steps. Sources: SECURITY.md:1-11, CONTRIBUTING.md:78-83