@vettly/mcp 0.1.4 → 0.1.5

package/README.md

@@ -1,12 +1,21 @@
 # @vettly/mcp
 
-MCP server for Vettly decision infrastructure. Enables AI assistants to make governed, auditable decisions under explicit policy.
+MCP server for Vettly decision infrastructure. Enables AI assistants to make policy-governed, auditable content decisions.
+
+## Why MCP for Content Decisions?
+
+AI assistants are increasingly used in content creation and moderation workflows. With the Vettly MCP server:
+
+- **Governed decisions** - AI assistants check content against your explicit policies
+- **Audit trail** - Every decision made by AI is recorded with a decision ID
+- **Policy access** - Assistants can view and validate your policy configurations
+- **Usage visibility** - Check usage stats and recent decisions
 
 ## Installation
 
 ```bash
-npm install @vettly/mcp
-# or
+npm install -g @vettly/mcp
+# or run directly
 npx @vettly/mcp
 ```
 
@@ -16,6 +25,9 @@ npx @vettly/mcp
 
 Add to your `claude_desktop_config.json`:
 
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
@@ -23,7 +35,7 @@ Add to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "@vettly/mcp"],
       "env": {
-        "VETTLY_API_KEY": "vettly_live_xxx"
+        "VETTLY_API_KEY": "sk_live_xxx"
       }
     }
   }
@@ -32,33 +44,55 @@ Add to your `claude_desktop_config.json`:
 
 ### Environment Variables
 
-- `VETTLY_API_KEY` (required) - Your Vettly API key
-- `VETTLY_API_URL` (optional) - API URL (defaults to `https://api.vettly.dev`)
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `VETTLY_API_KEY` | Yes | Your Vettly API key |
+| `VETTLY_API_URL` | No | Custom API URL (default: `https://api.vettly.dev`) |
+
+---
 
 ## Available Tools
 
 ### `moderate_content`
 
-Check content against a Vettly decision policy.
+Check content against a Vettly policy. Returns a decision with full audit trail.
 
 **Parameters:**
-- `content` (required) - The content to moderate
-- `policyId` (required) - The policy ID to use
-- `contentType` (optional) - `text`, `image`, or `video` (default: `text`)
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `content` | string | Yes | The content to check |
+| `policyId` | string | Yes | Policy ID to apply |
+| `contentType` | string | No | `text`, `image`, or `video` (default: `text`) |
 
-**Example:**
+**Example prompts:**
 ```
-Moderate this text: "Hello world" using policy "default-policy"
+Check if this text is safe: "Hello world" using the "community-safe" policy
+
+Moderate this user comment using my default-policy:
+"This product is terrible and the company should be ashamed"
+
+Is this image appropriate for my platform? Use the strict policy.
+[image URL]
 ```
 
+**Response includes:**
+- `decisionId` - Unique ID for audit trail
+- `action` - `allow`, `warn`, `flag`, or `block`
+- `categories` - Array of category scores and thresholds
+- `safe` / `flagged` - Boolean indicators
+
+---
+
 ### `validate_policy`
 
-Validate a policy YAML without saving it.
+Validate a policy YAML without saving it. Useful for testing policy changes.
 
 **Parameters:**
-- `yamlContent` (required) - The YAML policy content to validate
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `yamlContent` | string | Yes | The YAML policy content |
 
-**Example:**
+**Example prompts:**
 ```
 Validate this policy YAML:
 name: my-policy
@@ -66,57 +100,188 @@ rules:
   - category: hate_speech
     threshold: 0.7
     action: block
+
+Check if this policy configuration is valid:
+[paste YAML]
 ```
 
+**Response includes:**
+- `valid` - Boolean indicating if policy is valid
+- `errors` - Array of validation errors (if any)
+
+---
+
 ### `list_policies`
 
-List all available decision policies in your account.
+List all available policies in your account.
 
 **Parameters:** None
 
+**Example prompts:**
+```
+What policies do I have configured?
+
+List my Vettly policies
+
+Show me all available moderation policies
+```
+
+**Response includes:**
+- Array of policies with `id`, `name`, `version`, `updatedAt`
+
+---
+
 ### `get_usage_stats`
 
-Get usage statistics including request counts, costs, and decision outcomes.
+Get usage statistics for your account.
 
 **Parameters:**
-- `days` (optional) - Number of days to include (1-365, default: 30)
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `days` | number | No | Days to include (1-365, default: 30) |
+
+**Example prompts:**
+```
+How many moderation requests have I made this month?
+
+Show my Vettly usage for the last 7 days
+
+What's my content moderation cost so far?
+```
+
+**Response includes:**
+- Request counts by content type
+- Cost breakdown
+- Decision outcome distribution
+
+---
 
 ### `get_recent_decisions`
 
-Get recent decisions with optional filtering.
+Get recent moderation decisions with optional filtering.
 
 **Parameters:**
-- `limit` (optional) - Number of decisions to return (1-50, default: 10)
-- `flagged` (optional) - Filter by flagged status
-- `policyId` (optional) - Filter by policy ID
-- `contentType` (optional) - Filter by content type
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `limit` | number | No | Results to return (1-50, default: 10) |
+| `flagged` | boolean | No | Filter by flagged status |
+| `policyId` | string | No | Filter by policy ID |
+| `contentType` | string | No | Filter by content type |
+
+**Example prompts:**
+```
+Show me the last 10 blocked content decisions
+
+What content was flagged recently?
+
+List recent moderation decisions for the community-safe policy
+```
+
+**Response includes:**
+- Array of decisions with `id`, `action`, `categories`, `createdAt`
+
+---
 
 ## Resources
 
+The MCP server exposes read-only resources for policy inspection.
+
 ### `vettly://policies`
 
-Read-only list of all available decision policies.
+List of all available policies.
+
+```
+Access the vettly://policies resource to see all policies
+```
 
 ### `vettly://policies/{policyId}`
 
-Read-only access to a specific policy's YAML configuration.
+Specific policy YAML configuration.
+
+```
+Show me the YAML for my community-safe policy
+
+What are the thresholds configured in default-policy?
+```
+
+---
 
 ## Programmatic Usage
 
+Use the server in your own MCP applications:
+
 ```typescript
-import { createVettlyMcpServer } from '@vettly/mcp';
+import { createVettlyMcpServer } from '@vettly/mcp'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 
 const server = createVettlyMcpServer({
   apiKey: process.env.VETTLY_API_KEY!,
-  apiUrl: 'https://api.vettly.dev', // optional
-});
+  apiUrl: 'https://api.vettly.dev'  // optional
+})
+
+// Connect to stdio transport (for Claude Desktop)
+const transport = new StdioServerTransport()
+await server.connect(transport)
 
-// Connect to your transport
-server.connect(transport);
+// Or use with other transports
+// server.connect(yourCustomTransport)
 ```
 
+---
+
+## Use Cases
+
+### Content Review Assistance
+
+```
+I'm reviewing user-submitted content for our platform. Can you check these
+submissions against our community-safe policy and tell me which ones
+need manual review?
+
+1. "Great product, highly recommend!"
+2. "This is garbage, you people are idiots"
+3. "Love the new features in this update"
+```
+
+### Policy Development
+
+```
+I want to create a new policy for our support chat. Can you help me
+write the YAML and then validate it?
+
+Requirements:
+- Block hate speech with threshold 0.6
+- Flag harassment for review at 0.7
+- Allow profanity up to 0.8
+```
+
+### Usage Monitoring
+
+```
+Can you check our moderation usage this week and let me know if we're
+on track for our monthly budget?
+```
+
+### Decision Audit
+
+```
+A user is appealing a content decision. Can you look up decision ID
+abc-123 and explain why their content was blocked?
+```
+
+---
+
+## Security
+
+- API keys are passed via environment variables, not in config files
+- The MCP server only has read access to policies (cannot create/modify)
+- Decision IDs can be used for audit trails but don't expose content
+
+---
+
 ## Links
 
-- [Vettly Documentation](https://docs.vettly.dev)
-- [Get an API Key](https://vettly.dev)
-- [MCP Specification](https://modelcontextprotocol.io)
+- [vettly.dev](https://vettly.dev) - Sign up
+- [docs.vettly.dev](https://docs.vettly.dev) - Documentation
+- [MCP Specification](https://modelcontextprotocol.io) - MCP docs
+- [@vettly/sdk](https://www.npmjs.com/package/@vettly/sdk) - Core SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vettly/mcp",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "mcpName": "io.github.code-with-brian/vettly",
   "description": "MCP server for Vettly decision API. AI-powered content decisions with policy governance.",
   "type": "module",