Content
# Interop
Interop is a powerful command-line interface tool designed to improve developer productivity by providing a unified interface for managing projects, executing commands, and integrating with AI assistants.
## What is Interop?
Interop serves as a bridge between your development projects, custom commands, and AI assistants. It allows you to:
- Organize multiple projects with metadata, commands, and validation
- Define and execute commands with project context awareness
- Configure multiple MCP (Model Context Protocol) servers for AI integration
- Streamline repetitive development tasks across different domains
## Core Features
- **Project Management**: Track and validate multiple project directories
- **Command Execution**: Run commands with project context and arguments
- **Dynamic Command Loading**: Load commands from multiple directories with precedence rules
- **Remote Configuration System**: Fetch and sync configurations from Git repositories with conflict resolution
- **AI Integration**: Multiple MCP servers to expose commands to AI assistants with enhanced metadata
- **Configuration Management**: TOML-based configuration with validation and conflict detection
- **Cross-Platform Support**: Works on Linux, macOS, and Windows
## Installation
### Using Homebrew (macOS/Linux)
```bash
brew install yigitozgumus/formulae/interop
```
### Building from Source
1. Clone the repository:
```bash
git clone https://github.com/yigitozgumus/interop.git
cd interop
```
2. Build the project:
```bash
go build -o interop ./cmd/cli
```
## Configuration
Interop uses a TOML configuration file at `~/.config/interop/settings.toml`. To edit it:
```bash
interop edit
```
### Configuration Structure
```toml
# Global settings
log_level = "verbose" # Options: error, warning, verbose
executable_search_paths = ["~/.local/bin", "~/bin"]
command_dirs = ["~/.config/interop/commands.d", "~/projects/shared/interop-commands"]
mcp_port = 8081 # Default MCP server port
# MCP Server Configurations
[mcp_servers.domain1]
name = "domain1"
description = "Domain-specific commands"
port = 8082
[mcp_servers.domain2]
name = "domain2"
description = "Another domain for commands"
port = 8083
# Project Definitions
[projects.project1]
path = "~/projects/project1"
description = "Project 1 description"
commands = [
{ command_name = "build", alias = "b" },
{ command_name = "test" }
]
[projects.project2]
path = "~/projects/project2"
description = "Project 2 description"
commands = [
{ command_name = "deploy", alias = "d" }
]
# Command Definitions
[commands.build]
cmd = "go build ./..."
description = "Build the project"
is_enabled = true
is_executable = false
# Assign to a specific MCP server
mcp = "domain1"
[commands.test]
cmd = "go test ./..."
description = "Run tests"
is_enabled = true
is_executable = false
[commands.deploy]
cmd = "deploy.sh"
description = "Deploy the project"
is_enabled = true
is_executable = true
mcp = "domain2"
# Command with Arguments, Version, and Examples
[commands.build-app]
cmd = "go build -o ${output_file} ${package}"
description = "Build a Go application"
version = "1.1.0"
is_enabled = true
is_executable = false
arguments = [
{ name = "output_file", type = "string", description = "Output file name", required = true },
{ name = "package", type = "string", description = "Package to build", default = "./cmd/app" }
]
examples = [
{
description = "Build the main application",
command = "interop run build-app output_file=my-app"
},
{
description = "Build a specific package",
command = "interop run build-app output_file=my-tool package=./cmd/tool"
}
]
```
## Project Management
Projects are the core organizational unit in Interop.
### Listing Projects
```bash
interop projects
```
Output example:
```
PROJECTS:
=========
📁 Name: project1
Path: ~/projects/project1
Status: Valid: ✓ | In $HOME: ✓
Description: Project 1 description
Commands:
⚡ build (alias: b)
Build the project
⚡ test
Run tests
📁 Name: project2
Path: ~/projects/project2
Status: Valid: ✓ | In $HOME: ✓
Description: Project 2 description
Commands:
⚡ deploy (alias: d)
Deploy the project
```
### Project Configuration
Each project includes:
- **Path**: Directory location (validated for existence)
- **Description**: Optional project description
- **Commands**: List of commands with optional aliases
## Dynamic Configuration Loading
Interop supports loading configuration definitions from multiple directories, enabling better organization and scalability for large configuration collections.
### Configuration
Add `command_dirs` to your global settings to specify directories containing configuration definition files:
```toml
command_dirs = [
"~/.config/interop/config.d",
"~/projects/shared/interop-configs"
]
```
### Configuration Directory Structure
Each directory can contain multiple `*.toml` files with configuration definitions:
```
~/.config/interop/config.d/
├── git-commands.toml
├── docker-commands.toml
├── dev-projects.toml
└── ai-prompts.toml
```
Example `git-commands.toml`:
```toml
[commands.git-status]
cmd = "git status"
description = "Show the working tree status"
version = "1.0.0"
is_enabled = true
mcp = "dev-tools"
[commands.git-pull]
cmd = "git pull --rebase"
description = "Fetch from and integrate with another repository"
version = "1.0.0"
is_enabled = true
mcp = "dev-tools"
```
Example `dev-projects.toml`:
```toml
[projects.my-api]
path = "~/projects/my-api"
description = "Main API project"
commands = [
{ command_name = "build", alias = "b" },
{ command_name = "test", alias = "t" }
]
```
### What Can Be Included
Configuration files in these directories can contain:
- **Commands** (`[commands.name]`) - Command definitions
- **Projects** (`[projects.name]`) - Project configurations
- **Prompts** (`[prompts.name]`) - AI prompt templates
- **MCP Servers** (`[mcp_servers.name]`) - MCP server definitions
### Precedence Rules
When configuration names conflict, Interop follows a clear precedence order:
1. **Main `settings.toml`** (highest priority)
2. **Configuration directories** in the order specified in `command_dirs`
3. **Files within directories** in alphabetical order
This ensures predictable configuration resolution and allows for easy overriding of shared configurations.
### Benefits
- **Organization**: Group related configurations in separate files
- **Sharing**: Share configuration collections across teams or projects
- **Modularity**: Enable/disable entire configuration sets by directory
## Remote Configuration System
Interop includes a powerful remote configuration system that allows you to fetch and manage configurations from Git repositories. This enables teams to share command definitions, maintain centralized configuration libraries, and keep local setups synchronized with remote sources.
### Overview
The remote configuration system:
- Fetches configurations from Git repositories
- Maintains local copies in `config.d.remote` and `executables.remote` directories
- Tracks file changes with SHA-256 hashing for incremental updates
- Automatically integrates remote configurations with local ones
- Provides conflict detection and resolution with local configurations taking precedence
### Managing Remote Configurations
#### Adding a Remote Repository
```bash
# Add a remote Git repository
interop config remote add my-team https://github.com/myteam/interop-configs.git
# Add with SSH (recommended for private repositories)
interop config remote add my-team git@github.com:myteam/interop-configs.git
```
#### Listing Remote Repositories
```bash
interop config remote show
```
Output example:
```
Remote Configurations:
======================
🔗 my-team
URL: git@github.com:myteam/interop-configs.git
Status: ✓ Valid Git URL
🔗 shared-tools
URL: https://github.com/company/shared-tools.git
Status: ✓ Valid Git URL
```
#### Fetching Remote Configurations
```bash
# Fetch from all configured remotes
interop config remote fetch
# Fetch from a specific remote
interop config remote fetch my-team
```
The fetch process:
1. **Clones** the repository to a temporary directory
2. **Validates** the repository structure (requires `config.d` and/or `executables` folders)
3. **Compares** file hashes to detect changes
4. **Syncs** only modified files to local remote directories
5. **Updates** version tracking with commit information
6. **Cleans up** files that were removed from the remote
#### Removing Remote Repositories
```bash
# Remove a specific remote
interop config remote remove my-team
# Clear all remote configurations and cached files
interop config remote clear
```
### Repository Structure Requirements
Remote repositories must follow this structure:
```
your-repo/
├── config.d/ # Configuration files (required)
│ ├── commands.toml # Command definitions
│ ├── projects.toml # Project configurations
│ └── mcp-servers.toml # MCP server definitions
└── executables/ # Executable files (optional)
├── deploy.sh
├── build-tool
└── scripts/
└── helper.py
```
#### Example Remote Configuration
`config.d/team-commands.toml`:
```toml
[commands.team-deploy]
cmd = "deploy.sh"
description = "Deploy using team standards"
is_executable = true
mcp = "team-tools"
version = "2.1.0"
arguments = [
{ name = "environment", type = "string", required = true, description = "Target environment" },
{ name = "force", type = "bool", default = false, description = "Force deployment" }
]
[commands.team-test]
cmd = "run-team-tests.sh"
description = "Run standardized team tests"
is_executable = true
mcp = "team-tools"
[mcp_servers.team-tools]
name = "team-tools"
description = "Team standardized tools"
port = 8084
```
### Local Integration
Remote configurations are automatically integrated into your local setup:
#### Directory Structure
```
~/.config/interop/
├── settings.toml # Your local settings
├── config.d/ # Local configurations
│ └── personal.toml
├── config.d.remote/ # Remote configurations (auto-managed)
│ ├── team-commands.toml
│ └── shared-tools.toml
├── executables/ # Local executables
├── executables.remote/ # Remote executables (auto-managed)
│ ├── deploy.sh
│ └── build-tool
└── versions.toml # Remote tracking metadata (auto-managed)
```
#### Precedence Rules
When configurations conflict, Interop follows this precedence:
1. **Local configurations** (`config.d/`) - highest priority
2. **Remote configurations** (`config.d.remote/`) - lower priority
3. **Main settings.toml** - fallback for global settings
This ensures your local customizations always take precedence while still benefiting from shared remote configurations.
### Conflict Detection and Resolution
The validation system provides comprehensive conflict detection:
```bash
interop validate
```
Example output with conflicts:
```
Configuration Overview
=====================
Configuration Sources:
---------------------
🏠 Main Settings: /Users/user/.config/interop/settings.toml
🏠 Command Directories:
🏠 /Users/user/.config/interop/config.d (2 files)
☁️ Remote Configuration:
✓ config.d.remote: Available (3 files)
✓ executables.remote: Available (5 files)
✓ Remote tracking: Active
⚠️ Potential Conflicts:
⚠️ Command 'deploy' exists in both local and remote configs
⚠️ Command 'test-suite' exists in both local and remote configs
→ Local configurations take precedence
Commands:
--------
🌐 ✓ deploy (Shell) (🏠 Local)
└─ My custom deploy script
└─ 🔌 Default MCP server (Port: 8081)
🌐 ✓ team-deploy (Shell) (☁️ Remote)
└─ Deploy using team standards
└─ 🔌 Assigned to MCP server: team-tools (Port: 8084)
```
### Version Tracking and Incremental Updates
Interop maintains detailed tracking of remote configurations:
#### Version Information
The system tracks:
- **File hashes** (SHA-256) for change detection
- **Last commit ID** for repository state
- **Fetch timestamps** for update history
- **File paths** for cleanup of removed files
#### Incremental Updates
Subsequent fetches are optimized:
- Only changed files are downloaded
- Removed files are cleaned up locally
- Commit history is preserved for rollback capability
- Network usage is minimized
### Git URL Validation
The system validates Git URLs to ensure compatibility:
#### Supported Formats
**SSH Format:**
```bash
git@github.com:user/repo.git
git@gitlab.com:user/repo.git
git@bitbucket.org:user/repo.git
```
**HTTPS Format:**
```bash
https://github.com/user/repo.git
https://gitlab.com/user/repo.git
https://bitbucket.org/user/repo.git
```
**Custom Git Servers:**
```bash
https://git.company.com/team/configs.git
git@git.company.com:team/configs.git
```
### Use Cases
#### Team Standardization
```bash
# Set up team-wide configurations
interop config remote add company-standards git@github.com:company/interop-standards.git
interop config remote fetch
# Now all team members have access to:
# - Standardized deployment scripts
# - Common development commands
# - Shared MCP server configurations
# - Team-specific project templates
```
#### Multi-Environment Management
```bash
# Different configurations for different environments
interop config remote add prod-tools git@github.com:company/prod-tools.git
interop config remote add dev-tools git@github.com:company/dev-tools.git
# Fetch environment-specific tools
interop config remote fetch prod-tools
interop config remote fetch dev-tools
```
#### Open Source Tool Collections
```bash
# Add community-maintained tool collections
interop config remote add awesome-dev-tools https://github.com/community/awesome-dev-tools.git
interop config remote fetch
```
### Best Practices
#### Repository Organization
1. **Separate concerns**: Use different repositories for different domains
2. **Version your configurations**: Tag releases for stable configuration sets
3. **Document commands**: Include comprehensive descriptions and examples
4. **Test configurations**: Validate configurations before pushing
#### Security Considerations
1. **Use SSH keys** for private repositories
2. **Review remote configurations** before fetching
3. **Keep sensitive data local** - don't put secrets in remote configs
4. **Audit remote sources** regularly
#### Team Workflow
1. **Centralize common tools** in team repositories
2. **Allow local overrides** for personal preferences
3. **Version control changes** to shared configurations
4. **Communicate updates** when shared configs change
### Troubleshooting
#### Common Issues
**Repository not found:**
```bash
# Check URL and access permissions
git clone <your-repo-url> # Test manually
```
**Invalid repository structure:**
```bash
# Ensure repository has config.d/ or executables/ directory
# Check repository contents match expected structure
```
**Conflicts with local configurations:**
```bash
# Use validation to identify conflicts
interop validate
# Rename local commands if needed
# Or remove remote repository if not needed
```
**Network issues:**
```bash
# Check internet connectivity
# Verify Git credentials are set up
# Try fetching manually: git clone <repo-url>
```
## Command Management
Interop provides a flexible command system that adapts to your workflow.
### Listing Commands
```bash
interop commands
```
Output example:
```
COMMANDS:
=========
⚡ Name: build
Status: Enabled: ✓ | Source: Script
Description: Build the project
MCP Server: domain1
⚡ Name: test
Status: Enabled: ✓ | Source: Script
Description: Run tests
⚡ Name: deploy
Status: Enabled: ✓ | Source: Executable
Description: Deploy the project
MCP Server: domain2
```
### Command Types
1. **Shell Commands**: Run through the system shell
```toml
[commands.list]
cmd = "ls -la"
```
2. **Executable Commands**: Run directly from configured paths
```toml
[commands.deploy]
cmd = "deploy.sh"
is_executable = true
```
3. **Project-bound Commands**: Run in the context of a specific project
```toml
[projects.project1]
commands = [{ command_name = "build" }]
```
4. **Commands with Arguments**: Templated commands with validation
```toml
[commands.build-app]
cmd = "go build -o ${output_file} ${package}"
arguments = [
{ name = "output_file", type = "string", required = true },
{ name = "package", type = "string", default = "./cmd/app" }
]
```
### Executing Commands
Run a command by name or alias:
```bash
# Simple command
interop run build
# Command with alias
interop run b # Runs the build command
# Command with arguments
interop run build-app output_file=myapp.exe
```
For project-bound commands, Interop automatically:
1. Changes to the project directory
2. Executes the command
3. Returns to the original directory
## MCP Server Integration
Interop includes robust support for AI integration via MCP (Model Context Protocol) servers.
### What are MCP Servers?
MCP servers expose your commands as tools that can be invoked by AI assistants like Claude. Each server can provide a different set of commands, allowing domain-specific organization.
### Managing MCP Servers
```bash
# Start servers
interop mcp start # Start default server
interop mcp start domain1 # Start specific server
interop mcp start --all # Start all servers
# Check status
interop mcp status # Default shows all servers
interop mcp status domain1 # Check specific server
# Stop servers
interop mcp stop domain1 # Stop specific server
interop mcp stop --all # Stop all servers
# Restart servers
interop mcp restart domain1 # Restart specific server
interop mcp restart --all # Restart all servers
# Port management
interop mcp port-check # Check if ports are available
# Get configuration for AI tools
interop mcp export # Export JSON configuration
```
### Multiple MCP Servers
You can organize commands by domain:
```toml
[mcp_servers.work]
name = "work"
description = "Work-related commands"
port = 8082
[mcp_servers.personal]
name = "personal"
description = "Personal project commands"
port = 8083
[commands.work-task]
cmd = "work-script.sh"
mcp = "work" # This command is available on the work server
[commands.personal-task]
cmd = "personal-script.sh"
mcp = "personal" # This command is available on the personal server
```
Each server exposes only the commands assigned to it, creating a clean separation between different domains.
### AI Assistant Integration
When an AI assistant connects to an MCP server, it can:
1. See available commands and their descriptions
2. Execute commands with arguments
3. Receive command outputs and errors
This creates a powerful interface where the AI can help you execute tasks based on natural language instructions.
## Command Arguments
Commands can have typed arguments with validation:
```toml
[commands.generate]
cmd = "generate.sh ${type} ${name} ${force}"
description = "Generate a new component"
arguments = [
{ name = "type", type = "string", description = "Component type", required = true },
{ name = "name", type = "string", description = "Component name", required = true },
{ name = "force", type = "bool", description = "Overwrite if exists", default = false }
]
```
### Argument Types
- **string**: Text values
- **number**: Numeric values (integers or decimals)
- **bool**: Boolean values (true/false)
### Argument Features
- **Required**: Mark arguments that must be provided
- **Default Values**: Set fallback values for optional arguments
- **Descriptions**: Document the purpose of each argument
- **Prefix**: Specify command-line flags to use for arguments (e.g., `--key`)
### Using Arguments
```bash
# Named arguments
interop run generate type=component name=Button
# Positional arguments (in order of definition)
interop run generate component Button true
```
### Prefixed Arguments
Prefixed arguments allow you to define command-line arguments with specific prefixes (such as `--keys` or `-f`). This is especially useful when working with scripts or tools that expect arguments in a specific format:
```toml
[commands.update-strings]
cmd="python3 scripts/update_strings.py"
description="Update localization strings"
arguments=[
{name = "keys", type="string", required = false, description = "Keys to update", prefix = "--keys"},
{name = "language", type="string", required = false, description = "Language code", prefix = "--language"},
{name = "verbose", type="bool", required = false, description = "Verbose output", prefix = "--verbose"}
]
```
When executing:
```bash
interop run update-strings --keys "key1 key2" --language en --verbose true
```
The actual command executed will be:
```bash
python3 scripts/update_strings.py --keys key1 key2 --language en --verbose
```
#### How Prefixed Arguments Work
1. For arguments with prefixes: Interop appends them to the command with their prefixes
2. For arguments without prefixes: Interop substitutes them in the command string using `${arg_name}` placeholders
3. Boolean arguments with prefixes: If the value is `true`, only the prefix is added; otherwise, the argument is omitted
4. Non-boolean arguments with prefixes: The prefix and value are added together
#### Benefits of Prefixed Arguments
- Works consistently across all shells (bash, fish, zsh, etc.)
- Arguments can be provided in any order
- No need to escape special characters in argument values
- Compatible with tools that require specific argument formats
## Enhanced Command Metadata
Interop supports rich metadata for commands to improve AI assistant integration and documentation.
### Version Information
Add version tracking to your commands:
```toml
[commands.deploy]
cmd = "deploy.sh"
description = "Deploy the application"
version = "2.1.0"
is_enabled = true
```
### Usage Examples
Provide concrete examples of how to use commands:
```toml
[commands.create-component]
cmd = "generate.sh ${type} ${name}"
description = "Generate a new component"
version = "1.0.0"
arguments = [
{ name = "type", type = "string", description = "Component type", required = true },
{ name = "name", type = "string", description = "Component name", required = true }
]
examples = [
{
description = "Create a React component",
command = "interop run create-component type=react name=Button"
},
{
description = "Create a Vue component",
command = "interop run create-component type=vue name=Header"
}
]
```
### Benefits for AI Integration
When commands include version and examples:
- **AI assistants** can provide more accurate suggestions
- **Documentation** is generated automatically
- **Team onboarding** becomes easier with concrete examples
- **Version tracking** helps with compatibility and updates
## Validation & Diagnostics
### Enhanced Configuration Validation
```bash
interop validate
```
The validation system provides comprehensive analysis of your configuration:
#### Configuration Sources Analysis
- **Main Settings**: Validates `settings.toml` exists and is accessible
- **Local Directories**: Shows file counts and accessibility of `config.d/`
- **Remote Directories**: Shows status of `config.d.remote/` and `executables.remote/`
- **Remote Tracking**: Indicates if remote version tracking is active
#### Conflict Detection
- **Command Conflicts**: Identifies commands defined in multiple sources
- **Precedence Rules**: Shows which configuration takes precedence
- **Visual Indicators**: Uses symbols to highlight conflicts and warnings
- **Source Attribution**: Shows whether each command comes from local or remote sources
#### Validation Checks
- Project paths exist and are accessible
- Command references are valid
- No conflicting aliases within the same scope
- Required command arguments have proper definitions
- MCP server ports don't conflict
- Command directory accessibility and TOML syntax
- Remote repository structure compliance
- Git URL format validation
#### Example Validation Output
```
Configuration Overview
=====================
Configuration Sources:
---------------------
🏠 Main Settings: /Users/user/.config/interop/settings.toml
🏠 Command Directories:
🏠 /Users/user/.config/interop/config.d (2 files)
☁️ Remote Configuration:
✓ config.d.remote: Available (3 files)
✓ executables.remote: Available (5 files)
✓ Remote tracking: Active
⚠️ Potential Conflicts:
⚠️ Command 'deploy' exists in both local and remote configs
→ Local configurations take precedence
MCP Servers:
-----------
🔌 Default MCP Server (Port: 8081)
└─ Commands: (commands with no MCP field)
🔌 team-tools MCP Server (Port: 8084)
└─ Team standardized tools
└─ Commands: 5
Commands:
--------
🌐 ✓ deploy (Shell) (🏠 Local)
└─ My custom deploy script
└─ 🔌 Default MCP server (Port: 8081)
🌐 ✓ team-deploy (Shell) (☁️ Remote)
└─ Deploy using team standards
└─ 🔌 Assigned to MCP server: team-tools (Port: 8084)
Legend:
-------
🌐 Global Command 🏠 Local Configuration
📂 Project-bound Command ☁️ Remote Configuration
🔄 Command Alias ⚠️ Warning/Conflict
✓ Enabled Command 🔌 MCP Server Association
❌ Disabled Command
✅ Configuration is valid!
```
### Port Checking
```bash
interop mcp port-check
```
This shows:
- Which ports are available
- Which ports are in use
- Which processes are using ports
## Logging Levels
Configure verbosity in settings:
```toml
log_level = "verbose" # Options: error, warning, verbose
```
## Advanced Features
### Executable Search Paths
Interop searches for executables in:
1. Configuration directory (`~/.config/interop/executables/`)
2. Additional paths specified in configuration
3. System PATH
```toml
executable_search_paths = ["~/.local/bin", "~/bin"]
```
## Development
### Project Structure
```
.
├── cmd/
│ └── cli/ # Main application entry point
├── internal/
│ ├── command/ # CLI command implementations
│ ├── display/ # Output formatting utilities
│ ├── edit/ # Project editing functionality
│ ├── logging/ # Logging with color control
│ ├── mcp/ # MCP server implementation
│ ├── project/ # Project management core
│ ├── settings/ # Configuration management
│ └── util/ # Shared utilities
├── dist/ # Distribution files
└── .github/ # GitHub workflows and templates
```
### Testing
Run the test suite:
```bash
go test ./...
```
## Quick Reference
### Remote Configuration Commands
```bash
# Remote repository management
interop config remote add <name> <git-url> # Add remote repository
interop config remote remove <name> # Remove remote repository
interop config remote show # List all remotes
interop config remote clear # Remove all remotes and cached files
# Fetching configurations
interop config remote fetch # Fetch from all remotes
interop config remote fetch <name> # Fetch from specific remote
# Validation and diagnostics
interop validate # Comprehensive configuration validation
interop mcp port-check # Check MCP server port availability
```
### Configuration File Locations
```bash
~/.config/interop/settings.toml # Main configuration file
~/.config/interop/config.d/ # Local configuration directory
~/.config/interop/config.d.remote/ # Remote configurations (auto-managed)
~/.config/interop/executables/ # Local executable files
~/.config/interop/executables.remote/ # Remote executables (auto-managed)
~/.config/interop/versions.toml # Remote tracking metadata (auto-managed)
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
