# AgenticWerx MCP Client

[![PyPI version](https://badge.fury.io/py/agenticwerx-mcp-client.svg)](https://badge.fury.io/py/agenticwerx-mcp-client)
[![Python Support](https://img.shields.io/pypi/pyversions/agenticwerx-mcp-client.svg)](https://pypi.org/project/agenticwerx-mcp-client/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Model Context Protocol (MCP) client that connects to the AgenticWerx Lambda MCP server using JSON-RPC 2.0 protocol to provide code analysis and rule management capabilities.

## 🚀 Quick Start

The AgenticWerx MCP Client supports two modes:

### CLI Mode - Direct Command Line Usage

```bash
# Get marketplace rules
uvx agenticwerx-mcp-client@latest --api-key YOUR_KEY get-rules

# Get custom rules (Pro/Pro Plus)
uvx agenticwerx-mcp-client@latest --api-key YOUR_KEY get-custom-rules --language python

# Get team rules (Pro Plus teams)
uvx agenticwerx-mcp-client@latest --api-key YOUR_KEY get-team-rules --category security

# Analyze code
uvx agenticwerx-mcp-client@latest --api-key YOUR_KEY analyze-code --file script.py

# Analyze code snippet
uvx agenticwerx-mcp-client@latest --api-key YOUR_KEY analyze-code \
  --code "print('hello')" --language python
```

**Features:**
- 🔍 Auto-detects programming language from file extensions
- 📦 Automatically chunks large files (>8KB) for analysis
- 📊 Aggregates results from multiple chunks
- 🎯 Supports 20+ programming languages

See [CLI_USAGE.md](CLI_USAGE.md) for detailed CLI documentation.

### MCP Server Mode - For IDE Integration

Add this configuration to your MCP-compatible IDE (Kiro, Amazon Q Developer, etc.):

```json
{
  "mcpServers": {
    "agenticwerx": {
      "command": "uvx",
      "args": ["agenticwerx-mcp-client@latest"],
      "env": {
        "AGENTICWERX_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Get Your API Key

1. Visit [AgenticWerx Dashboard](https://agenticwerx.com/dashboard)
2. Navigate to API Keys section
3. Create a new API key
4. Use it in CLI or MCP configuration

## 🛠️ Available Tools

### MCP Server Mode Tools

### **get_rules**
Get AgenticWerx marketplace rules from subscribed packages.

**Parameters:**
- `packageId` (optional): Specific package ID to filter rules
- `language` (optional): Filter by programming language (e.g., typescript, python, go)
- `framework` (optional): Filter by framework (e.g., react, nextjs, express)
- `category` (optional): Filter by category (e.g., security, api-design, testing)
- `severity` (optional): Filter by severity (critical, high, medium, low)
- `appliesTo` (optional): Filter by applies to (e.g., frontend, backend, api, all)
- `search` (optional): Search in rule titles and descriptions
- `ruleIds` (optional): Get specific rules by ID
- `detailed` (optional): Get full rule details (instructions, rationale, tags). Default: false
- `includeContent` (optional): Get complete rule content (markdown/JSON). Default: false
- `includePatterns` (optional): Include regex patterns (requires detailed=true). Default: false
- `limit` (optional): Maximum rules to return (1-200). Default: 50
- `offset` (optional): Skip N rules for pagination. Default: 0

### **get_custom_rules**
Get user-uploaded custom rules (Pro/Pro Plus only).

Custom rules are rules you've uploaded to your AgenticWerx account. These are private to your account and can be used alongside marketplace rules.

**Parameters:**
Same filtering options as `get_rules` (except `packageId`):
- `language`, `framework`, `category`, `severity`, `appliesTo`, `search`, `ruleIds`
- `detailed`, `includeContent`, `includePatterns`
- `limit`, `offset`

### **get_team_rules**
Get team-shared custom rules (Pro Plus teams only).

Team rules are custom rules shared across your Pro Plus team. These are visible to all team members and can be used alongside marketplace and custom rules.

**Parameters:**
Same filtering options as `get_rules` (except `packageId`):
- `language`, `framework`, `category`, `severity`, `appliesTo`, `search`, `ruleIds`
- `detailed`, `includeContent`, `includePatterns`
- `limit`, `offset`

### **analyze_code**
Analyze code using AgenticWerx rules from the server.

**Parameters:**
- `code` (required): Code snippet to analyze
- `language` (optional): Programming language
- `packageIds` (optional): Array of package IDs to use for analysis

**Example:**
```json
{
  "tool": "analyze_code",
  "code": "print('hello world')",
  "language": "python",
  "packageIds": ["stripe-integration-excellence-pack"]
}
```

The tool connects to AgenticWerx services and retrieves the rules, which are then processed and returned to your IDE.

### **External MCP Server Tools** 🆕

Connect to external MCP servers (GitHub, AWS Docs, PostgreSQL, etc.) alongside AgenticWerx rules.

#### **list_external_mcp_servers**
Discover available external MCP servers from the AgenticWerx registry.

**Parameters:** None

**Returns:** List of pre-configured servers (GitHub, AWS Docs, PostgreSQL, etc.)

#### **get_external_mcp_server**
Get connection details for a specific external MCP server.

**Parameters:**
- `serverId` (required): Server ID from registry (e.g., "github", "aws-documentation")

**Returns:** Command, arguments, and required environment variables

#### **connect_external_server**
Connect to an external MCP server. Supports two modes:

**Mode A - Using serverId (Recommended):**
```json
{
  "serverId": "github",
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
  }
}
```

**Mode B - Manual Connection:**
```json
{
  "name": "custom-server",
  "command": "python",
  "args": ["my_server.py"],
  "env": {
    "CUSTOM_VAR": "value"
  }
}
```

**Features:**
- ✅ Automatic persistence - connections restored on restart
- ✅ Multiple simultaneous connections
- ✅ Tool discovery and execution
- ✅ Support for custom servers

#### **list_external_connections**
List all currently connected external MCP servers and their available tools.

#### **disconnect_external_server**
Disconnect from an external MCP server.

**Parameters:**
- `serverName` (required): Name of the server to disconnect

#### **call_external_tool**
Call a tool on a connected external MCP server.

**Parameters:**
- `serverName` (required): Name of the connected server
- `toolName` (required): Name of the tool to call
- `arguments` (optional): Arguments to pass to the tool

**See [EXTERNAL_MCP_SERVERS.md](EXTERNAL_MCP_SERVERS.md) for detailed documentation.**

## 🔗 Simple Connection

This client acts as a simple bridge between your IDE and AgenticWerx services. It retrieves rules and passes them back to your IDE for code analysis.

## 🔧 Installation Methods

### Method 1: UVX (Recommended)
No installation needed! Your IDE will automatically download and run the client:

```bash
uvx agenticwerx-mcp-client@latest --api-key your_key_here
```

### Method 2: pip install
```bash
pip install agenticwerx-mcp-client
agenticwerx-mcp-client --api-key your_key_here
```

### Method 3: From Source
```bash
git clone https://github.com/agenticwerx/mcp-client.git
cd mcp-client
pip install -e .
agenticwerx-mcp-client --api-key your_key_here
```

## 📋 IDE Configuration Examples

### Kiro IDE
```json
{
  "mcpServers": {
    "agenticwerx": {
      "command": "uvx",
      "args": ["agenticwerx-mcp-client@latest", "--api-key", "${AGENTICWERX_API_KEY}"],
      "env": {
        "AGENTICWERX_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Amazon Q Developer
```json
{
  "mcpServers": {
    "agenticwerx": {
      "command": "uvx",
      "args": ["agenticwerx-mcp-client@latest", "--api-key", "${AGENTICWERX_API_KEY}"],
      "env": {
        "AGENTICWERX_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### VS Code (with MCP extension)
```json
{
  "mcp.servers": {
    "agenticwerx": {
      "command": "uvx",
      "args": ["agenticwerx-mcp-client@latest", "--api-key", "${AGENTICWERX_API_KEY}"],
      "env": {
        "AGENTICWERX_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## 🔒 Security & Privacy

- **API Key Security:** Your API key is only used to authenticate with AgenticWerx services
- **Code Privacy:** Code analysis happens securely through encrypted connections
- **No Data Storage:** Your code is analyzed in real-time and not stored on our servers
- **Local Processing:** The MCP client runs locally on your machine

## 🚀 Features

- ✅ **Simple Connection:** Connects your IDE to AgenticWerx services
- ✅ **Rule Retrieval:** Fetches rules from the server
- ✅ **MCP Compatible:** Works with any MCP-compatible IDE
- ✅ **Zero Configuration:** Just add your API key
- ✅ **Lightweight:** Minimal overhead, just passes data through

## 📊 Example Output

```json
{
  "tool": "analyze",
  "packageId": "stripe-integration-excellence-pack",
  "rules": {
    "rules": [
      {
        "id": "rule-1",
        "name": "Security Rule",
        "description": "Prevents security vulnerabilities",
        "pattern": "eval\\(",
        "message": "Avoid using eval() as it can lead to code injection"
      }
    ],
    "metadata": {
      "package_name": "Security Rules",
      "version": "1.0.0",
      "total_rules": 1
    }
  }
}
```

## 🛠️ Technical Requirements

### Runtime Requirements
- Python 3.8+
- httpx >= 0.25.0
- mcp >= 1.0.0
- pydantic >= 2.0.0

### Installation
```bash
# Via uvx (recommended)
uvx agenticwerx-mcp-client@latest --api-key your_key_here

# Via pip
pip install agenticwerx-mcp-client
```

## 📚 Documentation

- [Full Documentation](https://docs.agenticwerx.com/mcp-client)
- [API Reference](https://docs.agenticwerx.com/api)
- [Rule Package Catalog](https://agenticwerx.com/packages)
- [IDE Integration Guides](https://docs.agenticwerx.com/integrations)

## 🆘 Support

- **Documentation:** [docs.agenticwerx.com](https://docs.agenticwerx.com)
- **Email Support:** [support@agenticwerx.com](mailto:support@agenticwerx.com)
- **Community:** [Discord Server](https://discord.gg/agenticwerx)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

**Note:** This is a proprietary package developed and maintained exclusively by AgenticWerx. We do not accept external contributions at this time.

## 🔄 Changelog

### v1.0.0 (2025-01-XX)
- Initial release
- Full MCP protocol support
- Rule retrieval tools
- Multi-language support
- Real-time code feedback

---

**Built with ❤️ by the AgenticWerx Team**

*Making code quality accessible to every developer, in every IDE, for every language.*