# Plugins Architecture
This document describes the plugins architecture of the Claude Automation project, explaining how plugins work, how to create new plugins, and the existing plugin implementations.
## Overview
The plugin system provides extensibility to the Claude Automation project, allowing for:
1. Adding new tools to the MCP server
2. Extending the functionality of Claude Desktop
3. Integrating with external systems and applications
4. Customizing behavior without modifying core components
## Plugin System Design
### Core Concepts
- **Plugin**: A module that adds functionality to the system
- **Tool**: A specific capability that a plugin provides
- **Registration**: The process of making a plugin's tools available
- **Execution**: The invocation of a plugin's tools
### Plugin Structure
Each plugin consists of:
1. A JavaScript module file
2. Tool definitions with schemas
3. Implementation handlers for each tool
4. Optional initialization and cleanup functions
Basic plugin structure:
```javascript
// Example plugin structure
export default {
name: "example-plugin",
version: "1.0.0",
description: "Example plugin for demonstration",
// Called when the plugin is loaded
initialize: async (context) => {
// Setup code here
},
// Tools provided by this plugin
tools: [
{
name: "example-tool",
description: "An example tool",
parameters: {
// JSON Schema for parameters
},
handler: async (params, context) => {
// Implementation
return { result: "success" };
}
}
],
// Called when the plugin is unloaded
cleanup: async () => {
// Cleanup code here
}
};
```
## Plugin Loading Process
1. The plugin manager scans the plugins directory
2. Each plugin module is loaded dynamically
3. The plugin's initialize function is called with context
4. The plugin's tools are registered with the MCP server
5. The plugin becomes available for use
## Plugin Context
Plugins receive a context object that provides:
- Access to system services and utilities
- Configuration settings
- Logging facilities
- Session information
- Inter-plugin communication
## Existing Plugins
### code-to-desktop-plugin.js
**Purpose**: Enables integration between Claude Code and Claude Desktop.
**Tools**:
- `code_context`: Provides code context from editor to Claude
- `code_completion`: Gets code completion suggestions
- `code_reference`: Finds references in code
- `code_explanation`: Explains code segments
- `code_implementation`: Suggests implementations
**Usage Example**:
```javascript
// Using the code context tool
const result = await mcpClient.executeTool("code_context", {
filePath: "/path/to/file.js",
selection: { start: 10, end: 20 }
});
```
### file-operations-plugin.js
**Purpose**: Provides file system operation capabilities.
**Tools**:
- `file_read`: Reads file contents
- `file_write`: Writes to files
- `file_list`: Lists directory contents
- `file_search`: Searches for files
- `file_delete`: Deletes files
**Usage Example**:
```javascript
// Using the file read tool
const content = await mcpClient.executeTool("file_read", {
path: "/path/to/file.txt"
});
```
## Creating New Plugins
### Step 1: Create Plugin File
Create a new JavaScript file in the plugins directory:
```javascript
// my-new-plugin.js
export default {
name: "my-new-plugin",
version: "1.0.0",
description: "My custom plugin",
initialize: async (context) => {
console.log("Plugin initialized");
},
tools: [
{
name: "my-custom-tool",
description: "A custom tool",
parameters: {
type: "object",
properties: {
input: {
type: "string",
description: "Input for the tool"
}
},
required: ["input"]
},
handler: async (params, context) => {
// Tool implementation
return {
output: `Processed: ${params.input}`
};
}
}
],
cleanup: async () => {
console.log("Plugin cleanup");
}
};
```
### Step 2: Register the Plugin
Add the plugin to the configuration:
```json
{
"plugins": [
"code-to-desktop-plugin.js",
"file-operations-plugin.js",
"my-new-plugin.js"
]
}
```
### Step 3: Use the Plugin
The new tool will be automatically available through the MCP server:
```javascript
const result = await mcpClient.executeTool("my-custom-tool", {
input: "Hello, world!"
});
```
## Plugin Best Practices
1. **Validation**: Always validate input parameters before processing
2. **Error Handling**: Implement comprehensive error handling
3. **Resource Management**: Clean up resources in the cleanup function
4. **Documentation**: Document tools and parameters thoroughly
5. **Security**: Respect security boundaries and user permissions
6. **Performance**: Optimize for performance, especially for frequently used tools
7. **Compatibility**: Ensure compatibility with different environments
## Plugin Lifecycle
1. **Loading**: Plugin is loaded by the plugin manager
2. **Initialization**: Plugin's initialize function is called
3. **Registration**: Plugin's tools are registered
4. **Execution**: Plugin's tools are executed as needed
5. **Cleanup**: Plugin's cleanup function is called on shutdown
6. **Unloading**: Plugin is unloaded from memory
## Plugin Dependencies
Plugins can have dependencies on:
- Core system components
- Other plugins
- External libraries
- System resources
Dependencies should be declared in the plugin's metadata and checked during initialization.
## Plugin Configuration
Plugins can be configured through:
- Global configuration in config files
- Plugin-specific configuration sections
- Environment variables
- Runtime configuration
Example configuration section:
```json
{
"plugins": {
"my-new-plugin": {
"enabled": true,
"settings": {
"timeout": 5000,
"maxItems": 100
}
}
}
}
```
## Plugin Security Considerations
1. **Sandboxing**: Plugins run in a controlled environment
2. **Permission Model**: Plugins have limited permissions by default
3. **User Consent**: User permission is required for sensitive operations
4. **Input Validation**: All inputs are validated before processing
5. **Output Sanitization**: All outputs are sanitized before returning
## Plugin Testing
To test a plugin:
1. Create a test script in the scripts directory
2. Use the MCP client to test tool execution
3. Verify tool results against expected outcomes
4. Test error conditions and edge cases
5. Test with different configurations
Example test script:
```javascript
// test-my-plugin.js
import { McpClient } from '../src/dev-hub-client.js';
async function testPlugin() {
const client = new McpClient();
try {
const result = await client.executeTool("my-custom-tool", {
input: "Test input"
});
console.log("Tool result:", result);
if (result.output === "Processed: Test input") {
console.log("Test passed!");
} else {
console.error("Test failed: Unexpected result");
}
} catch (error) {
console.error("Test failed:", error);
}
}
testPlugin();
```
## Troubleshooting Plugins
Common issues and solutions:
1. **Plugin not loading**: Check file path and syntax
2. **Tool not registered**: Verify tool definition and registration
3. **Execution failures**: Check error handling and parameter validation
4. **Performance issues**: Look for inefficient code or resource leaks
5. **Compatibility problems**: Ensure compatibility with system version
## Future Plugin System Enhancements
Planned enhancements to the plugin system:
1. Hot-reloading of plugins without restart
2. Plugin marketplace for sharing and discovery
3. Enhanced dependency management
4. Improved plugin isolation
5. More granular permission controls
