@impart-security/impart-mcp 0.1.3 → 0.2.0

package/README.md

@@ -6,12 +6,13 @@ A Model Context Protocol (MCP) implementation for interacting with Impart's API.
 ## Features
 
 - Rules Script Management
+- Rule Recipe Management
 - API Bindings Management
 - Endpoint Inventory
 - Tag Management
 - Observed Hosts Monitoring
 - Specification Management
-- List and Label Management
+- List Management
 - Inspector Management
 
 
@@ -23,45 +24,65 @@ You'll need to set up the following environment variables:
 
 ## Available Tools
 
-### Rules Scripts
-- `list_rules_scripts` - Get a list of rules scripts
-- `get_rules_script` - Get details of a specific rules script
-- `create_rules_script` - Create a new rules script
-- `update_rules_script` - Update an existing rules script
-- `validate_rules_script` - Validate a rules script
-- `write_rule_script` - Generate a rule script using Sparkle API
+This MCP server provides **26 tools** for managing Impart Security through the Model Context Protocol. All tools are automatically suffixed with your organization ID (e.g., `list_inspectors_d3ce`).
 
-### API Bindings
-- `list_api_bindings` - Get a list of API bindings
-- `create_api_binding` - Create a new API binding
+### Inspectors
+- **`list_inspectors`** - Get a list of inspectors for the organization
 
-### Endpoints and Specs
-- `list_endpoints` - Get an inventory of endpoints
-- `list_specs` - Get a list of specs
-- `get_spec` - Get details of a specific spec
+### Rules Scripts
+- **`list_rules_scripts`** - Get a list of rules scripts with filtering options (type, labels, disabled status)
+- **`get_rules_script`** - Get details of a specific rules script including source code and revisions
 
-### Tags and Metrics
-- `list_tags` - Get a list of tags
-- `get_tag_metrics` - Get timeseries metrics for tags
+### Rule Recipes (AI-Powered)
+- **`list_rule_recipes`** - Get a list of rule recipes with search filtering
+- **`get_rule_recipe`** - Get complete details of a specific rule recipe including components
+- **`generate_rule_recipe`** ✨ - Generate rule recipe configurations using Impart's AI (Sparkle)
+- **`create_rule_recipe`** - Create a new rule recipe from a configuration (typically from generate_rule_recipe)
 
-### Observed Hosts
-- `list_observed_hosts` - Get a list of observed hosts
-- `get_observed_host` - Get details of a specific observed host
+### API Specs & Endpoints
+- **`list_specs`** - Get a list of API specifications with search filtering
+- **`get_spec`** - Get details of a specific API spec including revision history
+- **`list_endpoints`** - Get inventory of API endpoints with extensive filtering (deprecated status, source, tags, methods, labels)
 
-### Lists and Labels
-- `list_lists` - Get a list of lists
-- `get_list_items` - Get items from a specific list
-- `create_list` - Create a new list
-- `update_list_items` - Update items in a list
-- `create_label` - Create a new label
-- `list_labels` - Get a list of labels
+### API Bindings
+- **`list_api_bindings`** - Get a list of API bindings with filtering by spec or collection
+- **`create_api_binding`** - Create new API bindings for connecting specs to infrastructure
 
-### Inspectors
-- `list_inspectors` - Get a list of inspectors
+### Tags & Metrics
+- **`list_tags`** - Get a list of tags with label filtering
+- **`get_tag_metrics`** - Get timeseries metrics for tags (HTTP requests, attacks, blocks, etc.) with flexible time ranges and rollup options
 
+### Observed Hosts
+- **`list_observed_hosts`** - Get a list of observed hosts in your infrastructure
+- **`get_observed_host`** - Get detailed information about a specific observed host
+
+### Lists (Allow/Block Lists)
+- **`list_lists`** - Get a list of lists with filtering by kind (ip, string, uuid, country, path, asn), subkind, and labels
+- **`get_list_items`** - Get items from a specific list with pagination
+- **`create_list`** - Create new lists for IP addresses, strings, UUIDs, countries, paths, or ASNs
+- **`update_list_items`** - Update items in an existing list
+
+### Labels
+- **`list_labels`** - Get a list of labels with search filtering
+- **`create_label`** - Create new labels with customizable colors and display names
+
+### Test Cases
+- **`list_test_cases`** - Get a list of rules test cases for validating rule behavior
+- **`get_test_case`** - Get detailed information about a specific test case
+
+### HTTP Requests (Traffic Analysis)
+- **`get_requests`** - Get HTTP requests captured by Impart with extensive filtering options:
+  - Time ranges (relative like `-1d`, `-24h` or absolute timestamps)
+  - Status codes, tags, IPs, external request IDs, rule IDs
+  - API specs, collections, endpoints
+  - Pagination with up to 1000 results per request
+  - Sort order (ascending/descending)
+  - Data source selection (PostgreSQL or ClickHouse)
+- **`get_request_details`** - Get complete details of a specific HTTP request including headers, body, and processing information
 
 ## Connecting to MCP Clients
 
+
 ### Claude Desktop
 
 To use Impart MCP with Claude Desktop, you'll need to configure the MCP server in Claude's configuration file. Here's how:
@@ -82,7 +103,6 @@ To use Impart MCP with Claude Desktop, you'll need to configure the MCP server i
            "impart": {
                "command": "npx",
                "args": [
-                   "-y",
                    "@impart-security/impart-mcp"
                ],
                "env": {
@@ -118,10 +138,7 @@ Add the Impart MCP server configuration:
   "mcpServers": {
     "impart": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@impart-security/impart-mcp"
-      ],
+      "args": ["@impart-security/impart-mcp"],
       "env": {
         "IMPART_AUTH_TOKEN": "your_auth_token"
       }
@@ -132,10 +149,34 @@ Add the Impart MCP server configuration:
 
 Make sure to update the environment variables with your Impart credentials.
 
+## Testing
+
+Comprehensive test suite with regression tests for all critical fixes.
+
+```bash
+# Run all tests
+npm run build
+cd testing
+./test-all.sh
+```
+
+**For complete testing documentation**, see [testing/TESTING.md](./testing/TESTING.md)
+
+Quick links:
+- [Testing Guide](./testing/TESTING.md) - Complete guide with all fixes documented
+- [Claude Desktop Setup](./testing/CLAUDE_DESKTOP_SETUP.md) - Integration guide
+- [Sample Outputs](./testing/SAMPLE_OUTPUTS.md) - Real API examples
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+When contributing:
+1. Run `npm run build` to compile
+2. Run `cd testing && ./test-all.sh` to verify tests pass
+3. Add tests for new features or bug fixes
+4. Update documentation
+
 ## License
 
 ISC