# Cline Rules for Ayzenberg AI

## Important Rules:

- There is documentation related to specific aspects of this codebase in the /docs directory. Please consult these files early and often to reduce errors.
- When you finish a task, always update the relevent documentation files as needed. Be brief, and if relevant, include a log entry at the bottom of the file summarizing what was done and the rationale.
- Whenever you discover new information that would be relevant for anyone new to the codebase, please add it to the ./clinerules file.
- Whenever you are implementing a new piece of functionality, always check to see if there are existing features or classes that you can use as an example. It is extremely important that you follow the same patterns across different parts of the codebase for consistency.
- When adding new functionality, create simple tests in the /tests directory that you can run via the CLI
- At the end of a task where you've added new functionality, always run the corresponding test to confirm that it is working

## Coding Guidelines

- Follow the DRY principal (Don't Repeat Yourself)
- Where relevant, follow the Single Responsibility Principal
  - Use this to avoid long files. Any files with over 800 lines of code will likely overload your context window.
- Use loose coupling and follow modular coding practices wherever possible
- Make extensive use of inline comments and do not remove existing inline comments unless they are no longer relevant.
- Always try to use the 'replace_in_file' tool first. Only use 'write_to_file' as a last resort and remember: for very long files it may overload your context window.
- Never use console.log(), instead use the logger utility function in this project, as it is scoped by environment. This will prevent unecessary logging in production. If there is no logger utility in this project, please create one.
- NEVER edit the .env file

# MCP Server Development Protocol

⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️

## Step 1: Planning (PLAN MODE)

- What problem does this tool solve?
- What API/service will it use?
- What are the authentication requirements?
  □ Standard API key
  □ OAuth (requires separate setup script)
  □ Other credentials

## Step 2: Implementation (ACT MODE)

1. Bootstrap

   - For web services, JavaScript integration, or Node.js environments:
     ```bash
     npx @modelcontextprotocol/create-server my-server
     cd my-server
     npm install
     ```
   - For data science, ML workflows, or Python environments:
     ```bash
     pip install mcp
     # Or with uv (recommended)
     uv add "mcp[cli]"
     ```

2. Core Implementation

   - Use MCP SDK
   - Implement comprehensive logging
     - TypeScript (for web/JS projects):
       ```typescript
       console.error('[Setup] Initializing server...')
       console.error('[API] Request to endpoint:', endpoint)
       console.error('[Error] Failed with:', error)
       ```
     - Python (for data science/ML projects):
       ```python
       import logging
       logging.error('[Setup] Initializing server...')
       logging.error(f'[API] Request to endpoint: {endpoint}')
       logging.error(f'[Error] Failed with: {str(error)}')
       ```
   - Add type definitions
   - Handle errors with context
   - Implement rate limiting if needed

3. Configuration
   - Get credentials from user if needed
   - Add to MCP settings:
     - For TypeScript projects:
       ```json
       {
         "mcpServers": {
           "my-server": {
             "command": "node",
             "args": ["path/to/build/index.js"],
             "env": {
               "API_KEY": "key"
             },
             "disabled": false,
             "autoApprove": []
           }
         }
       }
       ```
     - For Python projects:

       ```bash
       # Directly with command line
       mcp install server.py -v API_KEY=key

       # Or in settings.json
       {
         "mcpServers": {
           "my-server": {
             "command": "python",
             "args": ["server.py"],
             "env": {
               "API_KEY": "key"
             },
             "disabled": false,
             "autoApprove": []
           }
         }
       }
       ```

## Step 3: Testing (BLOCKER ⛔️)

<thinking>
BEFORE using attempt_completion, I MUST verify:
□ Have I tested EVERY tool?
□ Have I confirmed success from the user for each test?
□ Have I documented the test results?

If ANY answer is "no", I MUST NOT use attempt_completion.
</thinking>

1. Test Each Tool (REQUIRED)
   □ Test each tool with valid inputs
   □ Verify output format is correct
   ⚠️ DO NOT PROCEED UNTIL ALL TOOLS TESTED

## Step 4: Completion

❗ STOP AND VERIFY:
□ Every tool has been tested with valid inputs
□ Output format is correct for each tool

Only after ALL tools have been tested can attempt_completion be used.

## Key Requirements

- ✓ Must use MCP SDK
- ✓ Must have comprehensive logging
- ✓ Must test each tool individually
- ✓ Must handle errors gracefully
- ⛔️ NEVER skip testing before completion

## Project-sepcific Guidelines