@vettly/mcp 0.1.8 → 0.1.10

package/dist/bin/vettly-mcp.cjs

@@ -15,7 +15,7 @@ var ModerateInputSchema = import_zod.z.object({
   policyId: import_zod.z.string().min(1).describe("The policy ID to use for moderation"),
   contentType: import_zod.z.enum(["text", "image", "video"]).default("text").describe("Type of content being moderated")
 });
-function registerModerateTool(server, client) {
+function registerModerateTool(server, client, demoMode = false) {
   server.tool(
     "moderate_content",
     "Check text, image, or video content against a Vettly moderation policy. Returns safety assessment with category scores.",
@@ -24,6 +24,13 @@ function registerModerateTool(server, client) {
       policyId: ModerateInputSchema.shape.policyId,
       contentType: ModerateInputSchema.shape.contentType
     },
+    {
+      title: "Moderate Content",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async (args) => {
       const input = ModerateInputSchema.parse(args);
       try {
@@ -32,24 +39,25 @@ function registerModerateTool(server, client) {
           policyId: input.policyId,
           contentType: input.contentType
         });
+        const text = JSON.stringify(
+          {
+            decisionId: result.decisionId,
+            safe: result.safe,
+            flagged: result.flagged,
+            action: result.action,
+            categories: result.categories,
+            provider: result.provider,
+            latency: result.latency,
+            cost: result.cost
+          },
+          null,
+          2
+        );
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(
-                {
-                  decisionId: result.decisionId,
-                  safe: result.safe,
-                  flagged: result.flagged,
-                  action: result.action,
-                  categories: result.categories,
-                  provider: result.provider,
-                  latency: result.latency,
-                  cost: result.cost
-                },
-                null,
-                2
-              )
+              text: text + (demoMode ? DEMO_FOOTER : "")
             }
           ]
         };
@@ -73,22 +81,30 @@ var import_zod2 = require("zod");
 var ValidateInputSchema = import_zod2.z.object({
   yamlContent: import_zod2.z.string().min(1).describe("The YAML policy content to validate")
 });
-function registerValidateTool(server, client) {
+function registerValidateTool(server, client, demoMode = false) {
   server.tool(
     "validate_policy",
     "Validate a Vettly policy YAML without saving it. Returns validation results with any syntax or configuration errors.",
     {
       yamlContent: ValidateInputSchema.shape.yamlContent
     },
+    {
+      title: "Validate Policy",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async (args) => {
       const input = ValidateInputSchema.parse(args);
       try {
         const result = await client.validatePolicy(input.yamlContent);
+        const text = JSON.stringify(result, null, 2);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(result, null, 2)
+              text: text + (demoMode ? DEMO_FOOTER : "")
             }
           ]
         };
@@ -108,19 +124,34 @@ function registerValidateTool(server, client) {
 }
 
 // src/tools/list-policies.ts
-function registerListPoliciesTool(server, client) {
+var import_zod3 = require("zod");
+function registerListPoliciesTool(server, client, demoMode = false) {
   server.tool(
     "list_policies",
     "List all moderation policies available in your Vettly account.",
-    {},
-    async () => {
+    {
+      status: import_zod3.z.enum(["active", "all"]).default("active").describe("Filter by policy status: active only or all policies")
+    },
+    {
+      title: "List Policies",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    async (args) => {
       try {
         const result = await client.listPolicies();
+        let policies = result;
+        if (args.status === "active" && Array.isArray(policies)) {
+          policies = policies.filter((p) => p.status !== "archived");
+        }
+        const text = JSON.stringify(policies, null, 2);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(result, null, 2)
+              text: text + (demoMode ? DEMO_FOOTER : "")
             }
           ]
         };
@@ -140,26 +171,34 @@ function registerListPoliciesTool(server, client) {
 }
 
 // src/tools/usage-stats.ts
-var import_zod3 = require("zod");
-var UsageStatsInputSchema = import_zod3.z.object({
-  days: import_zod3.z.number().min(1).max(365).default(30).describe("Number of days to include in statistics")
+var import_zod4 = require("zod");
+var UsageStatsInputSchema = import_zod4.z.object({
+  days: import_zod4.z.number().min(1).max(365).default(30).describe("Number of days to include in statistics")
 });
-function registerUsageStatsTool(server, client) {
+function registerUsageStatsTool(server, client, demoMode = false) {
   server.tool(
     "get_usage_stats",
     "Get usage statistics for your Vettly account including request counts, costs, and moderation outcomes.",
     {
       days: UsageStatsInputSchema.shape.days
     },
+    {
+      title: "Get Usage Stats",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async (args) => {
       const input = UsageStatsInputSchema.parse(args);
       try {
         const result = await client.getUsageStats(input.days);
+        const text = JSON.stringify(result, null, 2);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(result, null, 2)
+              text: text + (demoMode ? DEMO_FOOTER : "")
             }
           ]
         };
@@ -179,14 +218,14 @@ function registerUsageStatsTool(server, client) {
 }
 
 // src/tools/decisions.ts
-var import_zod4 = require("zod");
-var DecisionsInputSchema = import_zod4.z.object({
-  limit: import_zod4.z.number().min(1).max(50).default(10).describe("Number of decisions to return"),
-  flagged: import_zod4.z.boolean().optional().describe("Filter to only flagged content (true) or safe content (false)"),
-  policyId: import_zod4.z.string().optional().describe("Filter by specific policy ID"),
-  contentType: import_zod4.z.enum(["text", "image", "video"]).optional().describe("Filter by content type")
+var import_zod5 = require("zod");
+var DecisionsInputSchema = import_zod5.z.object({
+  limit: import_zod5.z.number().min(1).max(50).default(10).describe("Number of decisions to return"),
+  flagged: import_zod5.z.boolean().optional().describe("Filter to only flagged content (true) or safe content (false)"),
+  policyId: import_zod5.z.string().optional().describe("Filter by specific policy ID"),
+  contentType: import_zod5.z.enum(["text", "image", "video"]).optional().describe("Filter by content type")
 });
-function registerDecisionsTool(server, client) {
+function registerDecisionsTool(server, client, demoMode = false) {
   server.tool(
     "get_recent_decisions",
     "Get recent moderation decisions with optional filtering by outcome, content type, or policy.",
@@ -196,6 +235,13 @@ function registerDecisionsTool(server, client) {
       policyId: DecisionsInputSchema.shape.policyId,
       contentType: DecisionsInputSchema.shape.contentType
     },
+    {
+      title: "Get Recent Decisions",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    },
     async (args) => {
       const input = DecisionsInputSchema.parse(args);
       try {
@@ -210,11 +256,12 @@ function registerDecisionsTool(server, client) {
         if (input.contentType) {
           decisions = decisions.filter((d) => d.contentType === input.contentType);
         }
+        const text = JSON.stringify({ decisions }, null, 2);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify({ decisions }, null, 2)
+              text: text + (demoMode ? DEMO_FOOTER : "")
             }
           ]
         };
@@ -234,12 +281,13 @@ function registerDecisionsTool(server, client) {
 }
 
 // src/tools/index.ts
-function registerTools(server, client) {
-  registerModerateTool(server, client);
-  registerValidateTool(server, client);
-  registerListPoliciesTool(server, client);
-  registerUsageStatsTool(server, client);
-  registerDecisionsTool(server, client);
+var DEMO_FOOTER = "\n\n---\n\u{1F511} Demo mode (10 requests/day). Get your free API key at https://vettly.dev";
+function registerTools(server, client, demoMode = false) {
+  registerModerateTool(server, client, demoMode);
+  registerValidateTool(server, client, demoMode);
+  registerListPoliciesTool(server, client, demoMode);
+  registerUsageStatsTool(server, client, demoMode);
+  registerDecisionsTool(server, client, demoMode);
 }
 
 // src/resources/policies.ts
@@ -316,18 +364,198 @@ function registerResources(server, client) {
   registerPolicyResources(server, client);
 }
 
+// src/prompts/moderate-content-guide.ts
+function registerModerateContentGuide(server) {
+  server.prompt(
+    "moderate-content-guide",
+    "Step-by-step guide to moderating content with Vettly. Explains the workflow: list policies, moderate content, and interpret results.",
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are helping a user moderate content with Vettly. Follow this workflow:
+
+## Step 1: List available policies
+Use the \`list_policies\` tool to see what moderation policies are configured. Each policy has an ID and defines rules for what content is allowed or flagged.
+
+## Step 2: Moderate content
+Use the \`moderate_content\` tool with:
+- \`content\`: The text, image URL, or video URL to check
+- \`policyId\`: The policy ID from step 1
+- \`contentType\`: "text", "image", or "video"
+
+## Step 3: Interpret results
+The response includes:
+- \`safe\`: Boolean \u2014 whether the content passed moderation
+- \`flagged\`: Boolean \u2014 whether the content was flagged for review
+- \`action\`: The recommended action ("allow", "flag", or "block")
+- \`categories\`: Breakdown of category scores (e.g. hate speech, violence, sexual content)
+- \`decisionId\`: Unique ID for this decision, useful for auditing
+
+## Tips
+- Always list policies first so you know which policy ID to use.
+- For images and video, pass the URL as the \`content\` parameter.
+- Use \`get_recent_decisions\` to review past moderation outcomes.
+- Use \`get_usage_stats\` to check your account's usage and remaining quota.`
+          }
+        }
+      ]
+    })
+  );
+}
+
+// src/prompts/write-policy.ts
+var import_zod6 = require("zod");
+function registerWritePolicy(server) {
+  server.prompt(
+    "write-policy",
+    "Guide for writing a Vettly moderation policy in YAML. Optionally tailored to a specific platform type.",
+    { platform: import_zod6.z.string().optional().describe('The type of platform (e.g. "kids app", "marketplace", "social media", "dating app")') },
+    async (args) => {
+      const platformContext = args.platform ? `
+
+The user is building a **${args.platform}**. Tailor your policy suggestions to this platform type \u2014 consider what content categories matter most and what thresholds are appropriate.` : "";
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `You are helping a user write a Vettly moderation policy in YAML.${platformContext}
+
+## Policy YAML structure
+
+A Vettly policy is a YAML document that defines moderation rules in plain English. Here's the structure:
+
+\`\`\`yaml
+name: My Policy
+description: Brief description of what this policy covers
+
+rules:
+  - category: hate_speech
+    threshold: 0.7
+    action: block
+    description: Block hateful content targeting protected groups
+
+  - category: violence
+    threshold: 0.8
+    action: flag
+    description: Flag violent content for human review
+
+  - category: sexual_content
+    threshold: 0.5
+    action: block
+    description: Block explicit sexual content
+
+  - category: self_harm
+    threshold: 0.6
+    action: block
+    description: Block content promoting self-harm
+\`\`\`
+
+## Available categories
+Common categories: \`hate_speech\`, \`violence\`, \`sexual_content\`, \`self_harm\`, \`harassment\`, \`dangerous_content\`, \`spam\`
+
+## Actions
+- \`allow\` \u2014 let the content through
+- \`flag\` \u2014 mark for human review
+- \`block\` \u2014 reject the content
+
+## Thresholds
+- 0.0\u20130.3: Very sensitive (catches more, higher false positive rate)
+- 0.4\u20130.6: Moderate sensitivity
+- 0.7\u20131.0: High confidence only (fewer false positives)
+
+## Workflow
+1. Draft the YAML policy based on the user's requirements
+2. Use the \`validate_policy\` tool to check for errors
+3. Iterate until validation passes
+4. The user can then save the policy via the Vettly dashboard`
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/prompts/review-flagged-content.ts
+var import_zod7 = require("zod");
+function registerReviewFlaggedContent(server) {
+  server.prompt(
+    "review-flagged-content",
+    "Template for reviewing flagged moderation decisions. Optionally filtered to a specific policy.",
+    { policyId: import_zod7.z.string().optional().describe("Filter flagged decisions to a specific policy ID") },
+    async (args) => {
+      const policyFilter = args.policyId ? `
+
+Filter decisions to policy ID: \`${args.policyId}\`` : "";
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `You are helping a user review flagged moderation decisions in Vettly.${policyFilter}
+
+## Review workflow
+
+### Step 1: Fetch flagged decisions
+Use the \`get_recent_decisions\` tool with \`flagged: true\` to get recent flagged content.${args.policyId ? ` Also set \`policyId: "${args.policyId}"\` to filter by that policy.` : " Optionally filter by `policyId` or `contentType`."}
+
+### Step 2: Analyze each decision
+For each flagged decision, examine:
+- **Content**: What was submitted
+- **Categories**: Which categories triggered and their scores
+- **Action**: What action was taken (flag vs block)
+- **Policy**: Which policy was applied
+
+### Step 3: Provide recommendations
+For each flagged item, suggest one of:
+- **Approve**: The content is acceptable, the flag was a false positive
+- **Confirm block**: The content correctly violates the policy
+- **Adjust policy**: The threshold may need tuning (too sensitive or not enough)
+
+### Step 4: Check for patterns
+Use \`get_usage_stats\` to look at overall moderation trends. If many items are being flagged, the policy thresholds may need adjustment.
+
+## Tips
+- High category scores (>0.9) are almost always correct flags
+- Scores in the 0.5-0.7 range are where most false positives occur
+- If a category consistently flags incorrectly, raise its threshold in the policy`
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/prompts/index.ts
+function registerPrompts(server) {
+  registerModerateContentGuide(server);
+  registerWritePolicy(server);
+  registerReviewFlaggedContent(server);
+}
+
 // src/server.ts
+var DEMO_API_KEY = "vettly_test_demo_mcp_readonly";
 function createVettlyMcpServer(config) {
+  const demoMode = !config.apiKey;
+  const apiKey = config.apiKey || DEMO_API_KEY;
   const client = new import_sdk.ModerationClient({
-    apiKey: config.apiKey,
+    apiKey,
     apiUrl: config.apiUrl
   });
   const server = new import_mcp2.McpServer({
     name: "vettly",
     version: "0.1.0"
   });
-  registerTools(server, client);
+  registerTools(server, client, demoMode);
   registerResources(server, client);
+  registerPrompts(server);
   return server;
 }
 
@@ -335,22 +563,8 @@ function createVettlyMcpServer(config) {
 async function main() {
   const apiKey = process.env.VETTLY_API_KEY;
   if (!apiKey) {
-    console.error("Error: VETTLY_API_KEY environment variable is required");
-    console.error("");
-    console.error("Usage:");
-    console.error("  VETTLY_API_KEY=vettly_live_xxx npx @vettly/mcp");
-    console.error("");
-    console.error("Or configure in Claude Desktop:");
-    console.error("  {");
-    console.error('    "mcpServers": {');
-    console.error('      "vettly": {');
-    console.error('        "command": "npx",');
-    console.error('        "args": ["-y", "@vettly/mcp"],');
-    console.error('        "env": { "VETTLY_API_KEY": "vettly_live_xxx" }');
-    console.error("      }");
-    console.error("    }");
-    console.error("  }");
-    process.exit(1);
+    console.error("No VETTLY_API_KEY set \u2014 starting in demo mode (limited to 10 requests/day).");
+    console.error("Get your free API key at https://vettly.dev");
   }
   const server = createVettlyMcpServer({
     apiKey,

package/dist/bin/vettly-mcp.js

@@ -1,29 +1,15 @@
 #!/usr/bin/env node
 import {
   createVettlyMcpServer
-} from "../chunk-VZJIPBOX.js";
+} from "../chunk-PMBQ22Z2.js";
 
 // src/bin/vettly-mcp.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 async function main() {
   const apiKey = process.env.VETTLY_API_KEY;
   if (!apiKey) {
-    console.error("Error: VETTLY_API_KEY environment variable is required");
-    console.error("");
-    console.error("Usage:");
-    console.error("  VETTLY_API_KEY=vettly_live_xxx npx @vettly/mcp");
-    console.error("");
-    console.error("Or configure in Claude Desktop:");
-    console.error("  {");
-    console.error('    "mcpServers": {');
-    console.error('      "vettly": {');
-    console.error('        "command": "npx",');
-    console.error('        "args": ["-y", "@vettly/mcp"],');
-    console.error('        "env": { "VETTLY_API_KEY": "vettly_live_xxx" }');
-    console.error("      }");
-    console.error("    }");
-    console.error("  }");
-    process.exit(1);
+    console.error("No VETTLY_API_KEY set \u2014 starting in demo mode (limited to 10 requests/day).");
+    console.error("Get your free API key at https://vettly.dev");
   }
   const server = createVettlyMcpServer({
     apiKey,