@172ai/containers-mcp-server 1.0.2 → 1.0.3

package/README.md

@@ -16,6 +16,8 @@ npm install -g @172ai/containers-mcp-server
 # Run interactive setup
 containers-mcp-server --setup
 
+# Test configuration and authentication
+containers-mcp-server --test
 # Start the server
 containers-mcp-server
 ```

package/README.md.bak

@@ -0,0 +1,366 @@
+# 172.ai Container Management MCP Server
+
+A **Model Context Protocol (MCP) server** that provides AI assistants with access to the 172.ai container management platform. This server exposes powerful tools for managing containers, builds, files, and capabilities through a standardized MCP interface, enabling natural language interactions with your containerized applications.
+
+🌐 **Live Documentation**: [https://172.ai/#/mcp](https://172.ai/#/mcp)
+
+[![npm version](https://badge.fury.io/js/@172ai%2Fcontainers-mcp-server.svg)](https://www.npmjs.com/package/@172ai/containers-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Quick Start
+
+```bash
+# Install globally
+npm install -g @172ai/containers-mcp-server
+
+# Run interactive setup
+containers-mcp-server --setup
+
+# Start the server
+containers-mcp-server
+```
+
+## ✨ Features
+
+### Container Management
+- **List Containers**: Browse available containers with filtering options
+- **Get Container Details**: Retrieve detailed information about specific containers
+- **Create Container**: Create new container templates
+- **Update Container**: Modify existing container configurations
+- **Delete Container**: Remove containers from the system
+- **Copy Container**: Create copies of existing containers
+
+### Build Management
+- **Build Container**: Initiate container build processes
+- **Get Build Status**: Monitor build progress and status
+- **List Builds**: View build history for containers
+- **Get Build Logs**: Access detailed build logs and output
+
+### File Management
+- **List Container Files**: Browse files within containers
+- **Get File Content**: Read file contents
+- **Upload Files**: Add new files to containers
+- **Update Files**: Modify existing file contents
+- **Delete Files**: Remove files from containers
+
+### Capability Management
+- **List Capabilities**: View available system capabilities
+- **Get Capability Details**: Access detailed capability information
+- **Search Capabilities**: Find capabilities by name or description
+
+## Installation
+
+1. **Clone or create the MCP server directory**:
+   ```bash
+   mkdir containers-mcp-server
+   cd containers-mcp-server
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Configure environment variables**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+4. **Build the project**:
+   ```bash
+   npm run build
+   ```
+
+## Configuration
+
+### Environment Variables
+
+The server requires configuration through environment variables. Copy `.env.example` to `.env` and configure:
+
+#### Required Settings
+- `CONTAINER_API_URL`: Base URL for the container management API
+- Authentication (choose one):
+  - `API_KEY`: Your API key for authentication
+  - `OAUTH_TOKEN`: OAuth token for temporary access
+  - `OAUTH_CLIENT_ID` + `OAUTH_CLIENT_SECRET`: For automated token refresh
+
+#### Optional Settings
+- `NODE_ENV`: Environment (development, production, test)
+- `LOG_LEVEL`: Logging verbosity (error, warn, info, debug)
+- `RATE_LIMIT_PER_MINUTE`: API rate limiting
+- `REQUEST_TIMEOUT`: Request timeout in milliseconds
+- `MAX_RETRIES`: Number of retry attempts for failed requests
+
+### Authentication Methods
+
+The server supports three authentication methods:
+
+1. **API Key** (Recommended for production):
+   ```bash
+   API_KEY=your_api_key_here
+   ```
+
+2. **OAuth Token** (For temporary access):
+   ```bash
+   OAUTH_TOKEN=your_oauth_token_here
+   ```
+
+3. **OAuth Client Credentials** (For automated systems):
+   ```bash
+   OAUTH_CLIENT_ID=your_client_id_here
+   OAUTH_CLIENT_SECRET=your_client_secret_here
+   ```
+
+## Usage
+
+### Running the Server
+
+#### Development Mode
+```bash
+npm run dev
+```
+
+#### Production Mode
+```bash
+npm start
+```
+
+### Connecting to Claude Code
+
+1. **Add to your Claude Code configuration**:
+   ```json
+   {
+     "mcpServers": {
+       "containers": {
+         "command": "node",
+         "args": ["/path/to/containers-mcp-server/dist/server.js"],
+         "env": {
+           "CONTAINER_API_URL": "http://localhost:3000",
+           "API_KEY": "your_api_key_here"
+         }
+       }
+     }
+   }
+   ```
+
+2. **Restart Claude Code** to load the new server
+
+### Available Tools
+
+Once connected, you can use these tools in your AI conversations:
+
+#### Container Operations
+- `list_containers` - List available containers
+- `get_container` - Get detailed container information
+- `create_container` - Create new container templates
+- `update_container` - Update container configurations
+- `delete_container` - Remove containers
+- `copy_container` - Create container copies
+
+#### Build Operations
+- `build_container` - Start container builds
+- `get_build_status` - Check build progress
+- `list_builds` - View build history
+
+#### File Operations
+- `list_container_files` - Browse container files
+- `get_file_content` - Read file contents
+- `upload_file` - Add files to containers
+
+#### Capability Operations
+- `list_capabilities` - View available capabilities
+
+### Example Usage
+
+```typescript
+// List public containers
+await listContainers({ scope: 'public', limit: 10 });
+
+// Get container details
+await getContainer({ containerId: 'container-123' });
+
+// Build a container
+await buildContainer({ containerId: 'container-123' });
+
+// Upload a file
+await uploadFile({ 
+  containerId: 'container-123',
+  filePath: 'src/app.js',
+  content: 'console.log("Hello, world!");',
+  mimeType: 'application/javascript'
+});
+```
+
+## API Reference
+
+### Tool Parameters
+
+#### `list_containers`
+- `scope`: Filter by scope ('public', 'myCollection', 'all')
+- `limit`: Maximum number of results (1-100)
+- `offset`: Number of results to skip
+- `query`: Search query for filtering
+
+#### `get_container`
+- `containerId`: Container ID to retrieve
+
+#### `create_container`
+- `name`: Container name
+- `description`: Container description
+- `dockerfile`: Dockerfile content
+- `tags`: Array of tags (optional)
+- `isPrivate`: Privacy setting (optional)
+- `envVars`: Environment variables (optional)
+
+#### `build_container`
+- `containerId`: Container ID to build
+
+#### `upload_file`
+- `containerId`: Target container ID
+- `filePath`: File path within container
+- `content`: File content (base64 for binary files)
+- `mimeType`: MIME type (optional)
+
+## Error Handling
+
+The server provides comprehensive error handling with:
+
+- **Validation errors**: Invalid input parameters
+- **Authentication errors**: Invalid or missing credentials
+- **Authorization errors**: Insufficient permissions
+- **Network errors**: Connection issues
+- **Rate limiting**: API quota exceeded
+- **Timeouts**: Request timeouts
+
+All errors include:
+- Human-readable error messages
+- Error codes for programmatic handling
+- Request IDs for debugging
+- Troubleshooting hints
+
+## Development
+
+### Project Structure
+```
+containers-mcp-server/
+├── server.ts                 # Main server entry point
+├── auth.ts                   # Authentication management
+├── config.ts                 # Configuration management
+├── services/
+│   ├── containerService.ts   # Container management
+│   ├── buildService.ts       # Build management
+│   ├── fileService.ts        # File management
+│   └── capabilityService.ts  # Capability management
+├── utils/
+│   ├── errorHandler.ts       # Error handling utilities
+│   └── apiError.ts          # API error classes
+├── package.json
+├── tsconfig.json
+├── .env.example
+└── README.md
+```
+
+### Available Scripts
+- `npm run dev` - Development mode with hot reload
+- `npm run build` - Build for production
+- `npm run start` - Start production server
+- `npm run test` - Run tests
+- `npm run lint` - Code linting
+- `npm run clean` - Clean build artifacts
+
+### Adding New Tools
+
+1. **Define the tool in `server.ts`**:
+   ```typescript
+   this.server.registerTool("my_new_tool", {
+     title: "My New Tool",
+     description: "Description of what it does",
+     inputSchema: z.object({
+       param1: z.string(),
+       param2: z.number().optional()
+     })
+   }, async ({ param1, param2 }) => {
+     // Implementation
+   });
+   ```
+
+2. **Add service methods** in appropriate service files
+
+3. **Update documentation** and examples
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Failed**
+   - Check API key or OAuth credentials
+   - Verify the container API URL is correct
+   - Ensure the API key has required scopes
+
+2. **Connection Timeout**
+   - Check network connectivity
+   - Verify container service is running
+   - Increase `REQUEST_TIMEOUT` if needed
+
+3. **Rate Limiting**
+   - Reduce request frequency
+   - Check `RATE_LIMIT_PER_MINUTE` setting
+   - Consider using API key instead of OAuth
+
+4. **Build Failures**
+   - Check container configuration
+   - Verify Dockerfile syntax
+   - Review build logs for errors
+
+### Debug Mode
+
+Enable debug logging:
+```bash
+LOG_LEVEL=debug npm run dev
+```
+
+This provides detailed information about:
+- API requests and responses
+- Authentication flow
+- Error details and stack traces
+- Performance metrics
+
+## Security
+
+### Best Practices
+
+1. **Use API Keys**: Prefer API keys over OAuth tokens for production
+2. **Secure Storage**: Store credentials securely (environment variables, secrets manager)
+3. **Network Security**: Use HTTPS endpoints when possible
+4. **Access Control**: Use minimum required scopes
+5. **Monitoring**: Monitor API usage and errors
+
+### Security Features
+
+- **Request timeout protection**
+- **Rate limiting**
+- **Input validation**
+- **Error message sanitization**
+- **SSL/TLS certificate validation**
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support
+
+For issues and support:
+1. Check the troubleshooting section
+2. Review error messages and request IDs
+3. Enable debug logging for detailed information
+4. Create an issue with reproduction steps
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make changes with tests
+4. Submit a pull request
+
+Please follow the existing code style and include tests for new functionality.

package/dist/cli.js

@@ -51,6 +51,44 @@ if (process.argv.includes('--setup')) {
         process.exit(1);
     });
 }
+else if (process.argv.includes('--test')) {
+    // Test authentication without starting MCP server
+    console.error('🔍 Testing MCP server configuration and authentication...\n');
+    Promise.resolve().then(() => __importStar(require('./auth.js'))).then(({ authManager }) => {
+        Promise.resolve().then(() => __importStar(require('./config.js'))).then(({ config }) => {
+            console.error('📋 Configuration:');
+            console.error(`   Base URL: ${config.get('baseUrl')}`);
+            console.error(`   Environment: ${config.get('environment')}`);
+            console.error(`   Log Level: ${config.get('logLevel')}\n`);
+            console.error('🔑 Testing authentication...');
+            return authManager.testAuthentication();
+        }).then((isAuthenticated) => {
+            if (isAuthenticated) {
+                console.error('✅ Authentication successful\!\n');
+                console.error('🎉 MCP server is properly configured and ready to use.');
+                console.error('\nTo start the server:');
+                console.error('  containers-mcp-server\n');
+                console.error('To reconfigure:');
+                console.error('  containers-mcp-server --setup\n');
+                process.exit(0);
+            }
+            else {
+                console.error('❌ Authentication failed\!');
+                console.error('\nPlease check your credentials and try:');
+                console.error('  containers-mcp-server --setup\n');
+                process.exit(1);
+            }
+        }).catch((error) => {
+            console.error('❌ Test failed:', error.message);
+            console.error('\nTry running setup to fix configuration:');
+            console.error('  containers-mcp-server --setup\n');
+            process.exit(1);
+        });
+    }).catch((error) => {
+        console.error('Failed to load test modules:', error);
+        process.exit(1);
+    });
+}
 else {
     // Run normal server
     Promise.resolve().then(() => __importStar(require('./server.js'))).then(({ ContainerMCPServer }) => {

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;AAEA;;;GAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,yEAAyE;AACzE,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;IACrC,YAAY;IACZ,kDAAO,YAAY,IAAE,IAAI,CAAC,CAAC,EAAE,cAAc,EAAE,EAAE,EAAE;QAC/C,MAAM,KAAK,GAAG,IAAI,cAAc,EAAE,CAAC;QACnC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAC1B,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACjB,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,KAAK,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,oBAAoB;IACpB,kDAAO,aAAa,IAAE,IAAI,CAAC,CAAC,EAAE,kBAAkB,EAAE,EAAE,EAAE;QACpD,MAAM,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACxC,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAC7B,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACjB,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;QACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@172ai/containers-mcp-server",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "MCP server for 172.ai container management platform - enables AI assistants to manage containers, builds, and files",
   "main": "dist/cli.js",
   "bin": {