# MCP Canvas Dev

A **Model Context Protocol (MCP)** server for Canvas Medical API/SDK development assistance. This server provides streamlined access to Canvas Medical documentation and AI-powered development tools.

## 🚀 Quick Start

### 1. Installation
```bash
# Clone and install dependencies
git clone https://github.com/your-username/mcp-canvas.git
cd mcp-canvas
pnpm install
```

### 2. Configuration
```bash
# Copy environment template
cp packages/server/env.template packages/server/.env

# Edit with your API credentials
nano packages/server/.env
# Set CARA_CANVAS_API_KEY=your_api_key_here
# Contact nils@caramedical.com for API credentials
```

### 3. Build and Start
```bash
# Build the server
pnpm build

# Start in stdio mode (for MCP clients like Claude Desktop)
pnpm dev

# Start in HTTP mode (for web applications)
STREAMABLE_HTTP=1 pnpm dev
```

## 🔧 Configuration Options

### Option 1: Use Public API (Recommended)
The server uses public API endpoints with API key authentication:

```bash
# Set environment variables in packages/server/.env (only API key needed for most users)
CARA_CANVAS_BASE_URL=https://k8zoi0cmul.execute-api.us-east-1.amazonaws.com/dev
CARA_CANVAS_API_KEY=your_api_key_here
```

**Need API credentials?** Email [nils@caramedical.com](mailto:nils@caramedical.com) to request access.

### Option 2: Deploy Your Own Lambda Proxy
For production use or custom knowledge bases, deploy your own Lambda proxy:

```bash
# Navigate to lambda-proxy directory
cd lambda-proxy

# Install dependencies
npm install

# Configure your AWS credentials and Knowledge Base IDs
export API_KNOWLEDGE_BASE_ID=your_api_knowledge_base_id
export SDK_KNOWLEDGE_BASE_ID=your_sdk_knowledge_base_id

# Deploy to AWS
npm run deploy:dev
```

### Option 3: Use Your Own API Endpoints
Configure the server to use your own API endpoints:

```bash
# In packages/server/.env
CARA_CANVAS_BASE_URL=https://your-api-endpoint.com
CARA_CANVAS_API_KEY=your_api_key
```

## 🛠️ Available Tools

The server provides **9 streamlined tools** and **6 comprehensive prompts** for Canvas Medical development:

### 📚 Documentation Search
- **`search_api_docs`** - Search Canvas Medical API documentation
- **`search_sdk_docs`** - Search Canvas Medical SDK documentation  
- **`search_all_docs`** - Search all Canvas Medical documentation

### 🤖 AI-Powered Development
- **`generate_response`** - Generate AI responses using Canvas Medical documentation
- **`generate_code`** - Generate code examples for Canvas Medical API integration
- **`review_code`** - Review Canvas Medical integration code and provide suggestions
- **`smart_canvas_development`** - Intelligent assistant with automatic documentation search and code generation
- **`generate_canvas_manifest`** - Generate complete Canvas Medical plugin manifest files with proper structure and data access permissions
- **`validate_code_against_docs`** - Validate that code only uses documented APIs, methods, and imports from Canvas Medical documentation. Prevents hallucination of non-existent features.

### 🎯 Code Generation Prompts
- **`prompts.generate_code_from_docs`** - Generate complete code from Canvas Medical documentation search results
- **`prompts.implement_from_findings`** - Create complete implementation from research findings and documentation
- **`prompts.code_review`** - Review Canvas Medical integration code and provide suggestions
- **`prompts.api_implementation`** - Generate implementation guidance for Canvas Medical API features
- **`prompts.debug_assistance`** - Help debug issues with Canvas Medical API integration
- **`prompts.canvas_manifest_guide`** - Comprehensive guide for creating and understanding Canvas Medical plugin manifest files (CANVAS_MANIFEST.json)

### 🧠 Intelligent Auto-Triggering

The MCP server now automatically provides comprehensive responses for Canvas Medical development requests:

- **Plugin Development**: Auto-triggers documentation search and code generation
- **API Integration**: Automatically searches relevant API documentation  
- **SDK Development**: Provides SDK-specific guidance and examples
- **Physician Information**: Intelligent responses for clinical workflow questions

**Example**: Ask "create a plugin for canvas which creates a text in a note about what physician / clinician did the note" and get:
- 📚 Relevant API and SDK documentation
- 💻 Complete Python plugin code
- 🚀 Step-by-step implementation guide
- 🛠️ Best practices and deployment instructions

### 🔄 Code Generation Workflow

**Clear Path from Research to Implementation:**

1. **🔍 Research Phase:**
   - Use `search_api_docs` to find relevant Canvas Medical APIs
   - Use `search_sdk_docs` to understand Canvas Medical SDK patterns
   - Use `search_all_docs` for comprehensive documentation coverage

2. **📝 Code Generation Phase:**
   - Use `prompts.generate_code_from_docs` for documentation-based code generation
   - Use `prompts.implement_from_findings` for complete implementation from research
   - Get production-ready code with Canvas Medical best practices

3. **🔧 Development Phase:**
   - Use `prompts.code_review` to review and improve generated code
   - Use `prompts.debug_assistance` for troubleshooting
   - Use `prompts.api_implementation` for implementation guidance

**Example Workflow:**
```
1. search_api_docs("note creation") → Get API documentation
2. search_sdk_docs("plugin development") → Get SDK patterns  
3. prompts.generate_code_from_docs({
     request: "Create note analysis plugin",
     documentation: [API + SDK results],
     language: "Python"
   }) → Get complete implementation
4. prompts.code_review({code: generated_code}) → Review and improve
```

### 🛡️ Anti-Hallucination Measures

**Production-Ready Code Generation:**

The MCP server includes comprehensive anti-hallucination measures to ensure all generated code uses only documented Canvas Medical APIs:

#### **Documentation Search with Source Verification:**
- **Source verification** for each API and method
- **Anti-hallucination warnings** in all documentation results
- **Clear guidelines** on what can and cannot be used
- **Explicit warnings** about undocumented features

#### **Code Generation with Strict Validation:**
- **Source verification comments** in generated code
- **Validation for undocumented methods** and imports
- **Error handling** for non-existent APIs
- **Strict requirements** in all prompts

#### **Code Validation Tool:**
- **`validate_code_against_docs`** - Validates code against documentation
- **Detects undocumented APIs** and methods
- **Prevents hallucination** of non-existent features
- **Provides specific recommendations** for fixes

#### **Example Anti-Hallucination Workflow:**
```
User: "Create a Canvas plugin for note analysis"

MCP Server Response:
1. 🔍 search_api_docs("note analysis") → Get documented APIs with source verification
2. 🔍 search_sdk_docs("Canvas plugin development") → Get documented SDK methods
3. 📝 generate_canvas_manifest({...}) → Generate manifest with documented structure
4. 💻 prompts.generate_code_from_docs({...}) → Generate code with strict validation
5. 🔧 validate_code_against_docs({...}) → Validate generated code against documentation
```

**Result:** Complete Canvas Medical plugin with:
- ✅ Only documented APIs and methods
- ✅ Source verification for all components
- ✅ Anti-hallucination validation
- ✅ Proper error handling for undocumented features

## 📚 Documentation

- **[MCP Client Setup](#-mcp-client-setup)** - Detailed MCP client configuration
- **[Troubleshooting](#-troubleshooting)** - Common issues and solutions
- **[API Credentials](#-getting-api-credentials)** - How to get API access

### Prerequisites
- Node.js 18+
- pnpm

### Setup
```bash
# Install dependencies
pnpm install

# Build the server
pnpm build

# Run tests
pnpm test

# Start development server
pnpm dev
```

## 🛡️ Security

- **No credentials required** - Uses public API endpoints
- **Open source** - All code is publicly available
- **Environment variable** configuration for customization

## �� Documentation

- **[README.md](./README.md)** - This file with setup and usage instructions
- **[MCP Client Setup](#-mcp-client-setup)** - Detailed MCP client configuration
- **[Troubleshooting](#-troubleshooting)** - Common issues and solutions
- **[API Credentials](#-getting-api-credentials)** - How to get API access

## 🔒 Security & Privacy

### Public API Usage
- **API key required** - Contact nils@caramedical.com for credentials
- **No AWS credentials required** for basic usage
- **No sensitive data** stored in the repository
- **Public endpoints** available with API key authentication

### Custom Deployment
- Deploy your own Lambda proxy for production use
- Keep your AWS credentials private
- Use your own API keys and endpoints

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](./LICENSE) file for details.

## ��️ MCP Client Setup

The Canvas Medical MCP server works with various MCP-compatible applications. Here's how to set it up:

### **Claude Desktop (Anthropic)**

1. **Install Claude Desktop** from [Anthropic's website](https://claude.ai/download)

2. **Create configuration file:**
   ```bash
   # Create config directory
   mkdir -p ~/.config/claude-desktop
   
   # Create configuration file
   nano ~/.config/claude-desktop/claude_desktop_config.json
   ```

3. **Add MCP server configuration:**
   ```json
   {
     "mcpServers": {
       "canvas-medical": {
         "command": "node",
         "args": ["/path/to/your/mcp-canvas/packages/server/dist/index.js"],
         "env": {
           "CARA_CANVAS_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   ```

4. **Restart Claude Desktop** and start using Canvas Medical tools!

### **Cursor IDE**

1. **Open Cursor IDE**

2. **Create MCP configuration:**
   ```bash
   # Create config directory
   mkdir -p ~/.cursor
   
   # Create configuration file
   nano ~/.cursor/mcp.json
   ```

3. **Add MCP server configuration:**
   ```json
   {
     "mcpServers": {
       "canvas-medical": {
         "command": "node",
         "args": ["/path/to/your/mcp-canvas/packages/server/dist/index.js"],
         "env": {
           "CARA_CANVAS_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   ```

4. **Restart Cursor** and use Canvas Medical tools in chat!

### **Continue.dev (VS Code Extension)**

1. **Install Continue extension** in VS Code

2. **Open Continue config** (`Cmd/Ctrl + Shift + P` → "Continue: Open Config")

3. **Add MCP server configuration:**
   ```json
   {
     "mcpServers": {
       "canvas-medical": {
         "command": "node",
         "args": ["/path/to/your/mcp-canvas/packages/server/dist/index.js"],
         "env": {
           "CARA_CANVAS_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   ```

4. **Restart VS Code** and use Canvas Medical tools!

### **Open WebUI**

1. **Install Open WebUI** with MCP support

2. **Configure MCP server** in settings:
   - **Server Name:** `canvas-medical`
   - **Command:** `node`
   - **Args:** `["/path/to/your/mcp-canvas/packages/server/dist/index.js"]`
   - **Environment Variables:** `CARA_CANVAS_API_KEY=your_api_key_here`

3. **Start using Canvas Medical tools!**

### **LM Studio**

1. **Install LM Studio** with MCP support

2. **Configure MCP server** in settings:
   - **Server Path:** `/path/to/your/mcp-canvas/packages/server/dist/index.js`
   - **Environment Variables:** `CARA_CANVAS_API_KEY=your_api_key_here`

3. **Start using Canvas Medical tools!**

### **Custom Applications**

For custom applications that support MCP:

1. **Start the server:**
   ```bash
   cd packages/server
   CARA_CANVAS_API_KEY="your_api_key" pnpm dev
   ```

2. **Connect via stdio** or **HTTP mode:**
   ```bash
   # HTTP mode for web applications
   STREAMABLE_HTTP=1 CARA_CANVAS_API_KEY="your_api_key" pnpm dev
   ```

## 🔑 Getting API Credentials

**Need API credentials?** Email [nils@caramedical.com](mailto:nils@caramedical.com) to request access.

**Note:** Only the API key is required for most users. The server uses public endpoints by default.


## 🔧 Troubleshooting

### **Common Issues:**

**"API key is required" error:**
- Make sure `CARA_CANVAS_API_KEY` is set in your MCP client configuration
- Verify the API key is valid by emailing nils@caramedical.com

**"Cannot find module" error:**
- Make sure you've built the server: `pnpm build`
- Check that the path to `dist/index.js` is correct

**"Connection refused" error:**
- Verify the server is running: `pnpm dev`
- Check that the MCP client configuration is correct

**Tools not appearing:**
- Restart your MCP client after configuration changes
- Verify the server is running and accessible

### **Testing the Server:**

```bash
# Test the server directly
cd packages/server
CARA_CANVAS_API_KEY="your_api_key" pnpm dev
```

### **Getting Help:**

- **Issues:** [GitHub Issues](https://github.com/your-username/mcp-canvas/issues)
- **API Credentials:** [nils@caramedical.com](mailto:nils@caramedical.com)
- **Documentation:** Check the README.md for detailed examples