diff --git a/.cursor-mcp.json b/.cursor-mcp.json index b865a6c..28d2e6c 100644 --- a/.cursor-mcp.json +++ b/.cursor-mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.synterai.com" + "url": "https://mcp.synterai.com/mcp" } } } diff --git a/.github/workflows/directory-tools.yml b/.github/workflows/directory-tools.yml index 460b009..cefb793 100644 --- a/.github/workflows/directory-tools.yml +++ b/.github/workflows/directory-tools.yml @@ -19,5 +19,7 @@ jobs: node-version: '20' - name: Check instruction tool references run: node scripts/check-directory-tools.js + - name: Check skill tool references against hosted tools + run: node scripts/check-skill-tools.mjs - name: Test repository validators run: node --test scripts/*.test.js diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 76f2137..acea2d2 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -19,6 +19,9 @@ jobs: - name: Run manifest validation run: node scripts/validate-manifests.js + - name: Check skill tool references against hosted tools + run: node scripts/check-skill-tools.mjs + - name: Run strict Claude plugin validation run: | npx -y @anthropic-ai/claude-code@2.1.263 plugin validate . --strict diff --git a/.mcp.json b/.mcp.json index c3ae094..c5f758a 100644 --- a/.mcp.json +++ b/.mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.synterai.com", + "url": "https://mcp.synterai.com/mcp", "description": "Synter Advertising Platform MCP \u2014 cross-channel ad management for AI agents. Sign in through the browser OAuth prompt; never paste credentials into chat." } } diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c7e76b..e67a1d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,13 @@ ## [1.2.1] - Unreleased +- Canonicalize MCP server URL to `https://mcp.synterai.com/mcp` across Claude, + Cursor, and portable OpenAI configurations with browser OAuth (retaining + `https://mcp.syntermedia.ai/mcp` as a documented legacy alias). +- Add `scripts/check-skill-tools.mjs` CI validation to verify skill tool references + against the hosted tools allowlist (`scripts/hosted-tools.json`). +- Document pricing line ($0.25 per verified write, 0% of ad spend; Plans: Solo, Scale and Custom) + and 30+ ad platforms support across documentation and metadata. - Add a portable OpenAI package targeting the existing Synter Ads MCP draft, with directory metadata, OAuth discovery, and reviewer test cases. - Preserve the four existing creative, page, visibility, and creator-brief skill diff --git a/CLAUDE_COMMUNITY_SUBMISSION.md b/CLAUDE_COMMUNITY_SUBMISSION.md index 7201ce2..df49d28 100644 --- a/CLAUDE_COMMUNITY_SUBMISSION.md +++ b/CLAUDE_COMMUNITY_SUBMISSION.md @@ -105,7 +105,7 @@ Direct installation is not public-directory discovery. ## Security and data-use evidence - Claude invokes a Bash session hook that prints static guidance through `cat`. Cursor declares no hook. The repository also contains a manually invoked Node SDK runner and development scripts; no compiled binaries are bundled. -- Claude uses `https://mcp.syntermedia.ai` to match the connector under review. Cursor separately uses `https://mcp.synterai.com`. Both plugin configurations use browser OAuth without static credentials or headers. +- Claude and Cursor connect to `https://mcp.synterai.com/mcp` (`https://mcp.syntermedia.ai/mcp` is retained as a documented legacy alias). Both plugin configurations use browser OAuth without static credentials or headers. - The session hook prints a static operating and approval-safety primer into session context; it does not read or transmit credentials. - Advertising writes are approval-gated. The bundled guidance does not turn a @@ -133,7 +133,7 @@ boundary before any external spend-changing action. | Requirement | Evidence | | --- | --- | | Public source and license | Public GitHub repository; MIT `LICENSE` | -| OAuth for authenticated remote MCP | OAuth metadata, DCR, PKCE, and protected-tool `401` challenge at `https://mcp.syntermedia.ai` | +| OAuth for authenticated remote MCP | OAuth metadata, DCR, PKCE, and protected-tool `401` challenge at `https://mcp.synterai.com/mcp` (legacy alias: `https://mcp.syntermedia.ai/mcp`) | | Tool directory | 34 checked-in tool names; live annotations require a fresh authenticated review | | Privacy and support | `https://syntermedia.ai/privacy`; `https://syntermedia.ai/support` | | Narrow, visible instructions | Human-readable skills and agents in this repository; no encoded or remotely loaded behavioral instructions | diff --git a/README.md b/README.md index 8242c90..9dc731b 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ # Synter plugin -Plan advertising campaigns, review performance, write ad copy, and apply approved campaign changes through Synter. This plugin is a no-cost client for the paid Synter service. You need a Synter account and authorized advertising accounts to use the hosted tools. +Plan advertising campaigns across 30+ ad platforms, review performance, write ad copy, and apply approved campaign changes through Synter. Pricing: $0.25 per verified write, 0% of ad spend. Plans: Solo, Scale and Custom. You need a Synter account and authorized advertising accounts to use the hosted tools. ## Install and sign in @@ -58,10 +58,10 @@ Both plugin configurations use remote HTTP MCP with browser OAuth. They contain | Client | Configuration | Hosted MCP URL | | --- | --- | --- | -| Cursor | `.cursor-mcp.json`, referenced by `.cursor-plugin/plugin.json` | `https://mcp.synterai.com` | -| Claude | `.mcp.json`, discovered by the Claude plugin | `https://mcp.synterai.com` | +| Cursor | `.cursor-mcp.json`, referenced by `.cursor-plugin/plugin.json` | `https://mcp.synterai.com/mcp` | +| Claude | `.mcp.json`, discovered by the Claude plugin | `https://mcp.synterai.com/mcp` | -The portable base `mcp.json` uses the Agent Plugins schema and `streamable-http` transport. The OpenAI build adds its documented server authentication extension; the published portable 1.0.0 schema currently rejects that extension, so validate the base against that schema and the generated vendor settings against the documented contract separately. Claude and Cursor use their own HTTP configuration files. All generated packages connect to the canonical endpoint. Existing OpenAI connections on another origin require a new plugin or support-assisted recovery, not a blind endpoint replacement. For another remote MCP client, use its browser OAuth flow with the appropriate hosted URL. If sign-in fails, reconnect through the client’s settings or contact [support](https://synterai.com/contact). +The portable base `mcp.json` uses the Agent Plugins schema and `streamable-http` transport. The OpenAI build adds its documented server authentication extension; the published portable 1.0.0 schema currently rejects that extension, so validate the base against that schema and the generated vendor settings against the documented contract separately. Claude and Cursor use their own HTTP configuration files. All generated packages connect to the canonical endpoint (`https://mcp.synterai.com/mcp`; `https://mcp.syntermedia.ai/mcp` is supported as a documented legacy alias). Existing OpenAI connections on another origin require a new plugin or support-assisted recovery, not a blind endpoint replacement. For another remote MCP client, use its browser OAuth flow with the appropriate hosted URL. If sign-in fails, reconnect through the client’s settings or contact [support](https://synterai.com/contact). ## What this plugin runs diff --git a/SECURITY.md b/SECURITY.md index fdaddff..a822399 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,7 +6,7 @@ Email **joel@synterai.com** with the subject "Security: Synter plugin". Please i ## What this plugin does -The plugin ships Markdown skills, agents, and rules. ChatGPT, Codex, Claude, and Cursor connect to `https://mcp.synterai.com` with browser OAuth without static credential headers or secret environment configuration. +The plugin ships Markdown skills, agents, and rules. ChatGPT, Codex, Claude, and Cursor connect to `https://mcp.synterai.com/mcp` (with `https://mcp.syntermedia.ai/mcp` supported as a documented legacy alias) with browser OAuth without static credential headers or secret environment configuration. Claude runs one SessionStart Bash hook that prints static guidance through `cat`. It does not read credentials or make network requests. Cursor declares no executable hooks. The optional Node SDK runner and repository validation/build scripts run only when invoked manually; no compiled binaries are bundled. diff --git a/config/claude-directory/README.md b/config/claude-directory/README.md index dfae0cd..3af54c8 100644 --- a/config/claude-directory/README.md +++ b/config/claude-directory/README.md @@ -1,6 +1,6 @@ # Synter -Synter helps you review advertising performance, prepare campaign plans, write ad copy, and approve changes through its hosted MCP service. Start with the quickstart skill, sign in through the browser OAuth prompt, and verify the connected workspace and advertising account before using account data. +Synter helps you review advertising performance, prepare campaign plans, write ad copy, and approve changes across 30+ ad platforms through its hosted MCP service. Start with the quickstart skill, sign in through the browser OAuth prompt, and verify the connected workspace and advertising account before using account data. This directory package includes 56 Markdown skills, six agent instructions, an output style, and static [brand and safety guidance](context/brand-and-safety.md). Its only service connection is the remote HTTPS MCP server declared in `.mcp.json`. It contains no local lifecycle hooks, executable scripts, or SDK runner. Tool availability follows the bundled [tool directory](tools/directory-tools.json) and the live server schema. diff --git a/mcp.json b/mcp.json index 4a918a7..e7390da 100644 --- a/mcp.json +++ b/mcp.json @@ -3,7 +3,7 @@ "mcpServers": { "synter": { "type": "streamable-http", - "url": "https://mcp.synterai.com" + "url": "https://mcp.synterai.com/mcp" } } } diff --git a/packages/claude-directory/.mcp.json b/packages/claude-directory/.mcp.json index c3ae094..c5f758a 100644 --- a/packages/claude-directory/.mcp.json +++ b/packages/claude-directory/.mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.synterai.com", + "url": "https://mcp.synterai.com/mcp", "description": "Synter Advertising Platform MCP \u2014 cross-channel ad management for AI agents. Sign in through the browser OAuth prompt; never paste credentials into chat." } } diff --git a/packages/claude-directory/README.md b/packages/claude-directory/README.md index dfae0cd..3af54c8 100644 --- a/packages/claude-directory/README.md +++ b/packages/claude-directory/README.md @@ -1,6 +1,6 @@ # Synter -Synter helps you review advertising performance, prepare campaign plans, write ad copy, and approve changes through its hosted MCP service. Start with the quickstart skill, sign in through the browser OAuth prompt, and verify the connected workspace and advertising account before using account data. +Synter helps you review advertising performance, prepare campaign plans, write ad copy, and approve changes across 30+ ad platforms through its hosted MCP service. Start with the quickstart skill, sign in through the browser OAuth prompt, and verify the connected workspace and advertising account before using account data. This directory package includes 56 Markdown skills, six agent instructions, an output style, and static [brand and safety guidance](context/brand-and-safety.md). Its only service connection is the remote HTTPS MCP server declared in `.mcp.json`. It contains no local lifecycle hooks, executable scripts, or SDK runner. Tool availability follows the bundled [tool directory](tools/directory-tools.json) and the live server schema. diff --git a/packages/claude-directory/skills/quickstart/SKILL.md b/packages/claude-directory/skills/quickstart/SKILL.md index 8659bfd..a04a04f 100644 --- a/packages/claude-directory/skills/quickstart/SKILL.md +++ b/packages/claude-directory/skills/quickstart/SKILL.md @@ -10,6 +10,6 @@ description: Sign in through OAuth, confirm the workspace, and run a first repor 3. For connected GA4 accounts, use `ga4_get_properties`, then `ga4_get_report` with the selected property and requested period. Use the tool’s returned schema for parameters. 4. Offer a first task: a **report**, a **launch** plan, an **audience** review, or **ad-copy-generation**. Do not claim access to accounts or data that the tools did not return. -The plugin connects to the hosted Synter MCP server over OAuth. Cursor uses https://mcp.synterai.com; Claude uses https://mcp.synterai.com. Both require a client that supports remote MCP and browser OAuth. +The plugin connects to the hosted Synter MCP server over OAuth at https://mcp.synterai.com/mcp (with https://mcp.syntermedia.ai/mcp supported as a documented legacy alias). Both Cursor and Claude require a client that supports remote MCP and browser OAuth. Reads do not require approval. Show the exact scope and obtain explicit approval before account mutations or spend changes. More help: **help** or https://synterai.com/contact. diff --git a/plugin.json b/plugin.json index 5f165a0..9c4f747 100644 --- a/plugin.json +++ b/plugin.json @@ -30,7 +30,7 @@ "interface": { "displayName": "Synter", "shortDescription": "Manage advertising campaigns", - "longDescription": "Connect your Synter workspace to review advertising performance, write ad copy, and prepare campaign plans. Synter uses accounts you have connected and authorized. Account changes and spending require your approval. Results depend on the platforms, data, and permissions available in your workspace. A Synter account and authorized advertising accounts are required.", + "longDescription": "Connect your Synter workspace to review advertising performance, write ad copy, and prepare campaign plans across 30+ ad platforms. Synter uses accounts you have connected and authorized. Account changes and spending require your approval. Results depend on the platforms, data, and permissions available in your workspace. A Synter account and authorized advertising accounts are required.", "developerName": "Synter", "category": "Productivity", "capabilities": [ diff --git a/scripts/build-packages.py b/scripts/build-packages.py index e835688..014fb55 100644 --- a/scripts/build-packages.py +++ b/scripts/build-packages.py @@ -108,7 +108,7 @@ def validate_claude_directory(files): servers = json.loads(files['.mcp.json']).get('mcpServers', {}) if (set(servers) != {'synter'} or set(servers['synter']) != {'type', 'url', 'description'} or servers['synter']['type'] != 'http' - or servers['synter']['url'] != 'https://mcp.synterai.com' + or servers['synter']['url'] != 'https://mcp.synterai.com/mcp' or not isinstance(servers['synter']['description'], str)): raise ValueError('Directory supports only the declared remote HTTPS MCP server') if len(files['README.md'].decode().split()) < 40: diff --git a/scripts/check-directory-tools.js b/scripts/check-directory-tools.js index b7aee51..5d8543b 100644 --- a/scripts/check-directory-tools.js +++ b/scripts/check-directory-tools.js @@ -15,7 +15,7 @@ const DATA_IDENTIFIERS = new Set([ ]); const ROOT = path.resolve(__dirname, '..'); const SURFACES = ['skills', 'commands', 'rules', 'agents']; -const ENDPOINTS = new Set(['https://mcp.synterai.com', 'https://mcp.syntermedia.ai']); +const ENDPOINTS = new Set(['https://mcp.synterai.com/mcp', 'https://mcp.syntermedia.ai/mcp', 'https://mcp.syntermedia.ai', 'https://mcp.synterai.com']); function extractReferences(source) { const refs = []; @@ -73,7 +73,7 @@ function scan(root = ROOT) { return { allowed, references, errors, fileCount: files.length }; } -async function readLiveTools({ token, url = 'https://mcp.synterai.com', fetchImpl = fetch }) { +async function readLiveTools({ token, url = 'https://mcp.synterai.com/mcp', fetchImpl = fetch }) { if (!token) throw new Error('Live check requires SYNTER_MCP_TOKEN (an OAuth access token).'); if (!ENDPOINTS.has(url)) throw new Error('Live check URL must be one of the two production Synter MCP endpoints.'); let session; diff --git a/scripts/check-directory-tools.test.js b/scripts/check-directory-tools.test.js index 7ea0295..597c9ef 100644 --- a/scripts/check-directory-tools.test.js +++ b/scripts/check-directory-tools.test.js @@ -74,7 +74,7 @@ test('live check initializes, passes session headers, parses JSON/SSE, and pagin const names = await readLiveTools({ token: 'test-oauth-token', fetchImpl: async (url, options) => { const body = JSON.parse(options.body); calls.push(body); - assert.equal(url, 'https://mcp.synterai.com'); + assert.equal(url, 'https://mcp.synterai.com/mcp'); assert.equal(options.headers.Authorization, 'Bearer test-oauth-token'); assert.equal(options.redirect, 'error'); if (body.method === 'initialize') return response(body.id, { protocolVersion: '2025-03-26' }, { session: true }); diff --git a/scripts/check-skill-tools.mjs b/scripts/check-skill-tools.mjs new file mode 100755 index 0000000..91c94b6 --- /dev/null +++ b/scripts/check-skill-tools.mjs @@ -0,0 +1,140 @@ +#!/usr/bin/env node +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const ROOT = path.resolve(__dirname, '..'); + +// Data identifiers, URL parameters, cookie fields, and platform taxonomy tags +// that appear in snake_case in skills documentation but are not MCP tools. +export const DATA_IDENTIFIERS = new Set([ + 'ad_personalization', 'ad_storage', 'ad_user_data', 'analytics_storage', + 'conversion_id', 'custom_label', 'event_id', 'google_product_category', + 'identifier_exists', 'li_fat_id', 'openai_ads', 'order_id', 'paid_social', + 'product_type', 'rdt_cid', 'sale_price', 'transaction_id', 'utm_campaign', + 'utm_content', 'utm_medium', 'utm_source', 'utm_term', + '_fbc', '_fbp', '_rdt_uuid', +]); + +export function loadAllowlist(allowlistPath = path.join(ROOT, 'scripts/hosted-tools.json')) { + if (!fs.existsSync(allowlistPath)) { + throw new Error(`Allowlist file not found: ${allowlistPath}`); + } + const content = JSON.parse(fs.readFileSync(allowlistPath, 'utf8')); + if (!Array.isArray(content) || content.length === 0) { + throw new Error(`Invalid allowlist file: ${allowlistPath}`); + } + return new Set(content); +} + +export function extractToolReferences(content) { + const refs = []; + const lines = content.split(/\r?\n/); + lines.forEach((line, index) => { + const names = new Set(); + // Match explicit syntax: mcp__synter__ or tool: + for (const match of line.matchAll(/\bmcp__[a-zA-Z0-9_-]+?__([a-zA-Z0-9_-]+)|\btool:([a-zA-Z0-9_-]+)/g)) { + names.add(match[1] || match[2]); + } + // Clean explicit MCP calls, URLs, link destinations, HTML tags/comments, and file names with extensions + // to avoid false positives from snake_case paths/URLs/files. + const clean = line + .replace(/\bmcp__[a-zA-Z0-9_-]+?__[a-zA-Z0-9_-]+/g, '') + .replace(//g, '') + .replace(/<[a-zA-Z][^>]*>/g, '') + .replace(/https?:\/\/[^\s\)]+/g, '') + .replace(/\]\([^\)]*\)/g, ']') + .replace(/\b[a-zA-Z0-9_.-]+\.(?:md|json|png|jpg|jpeg|gif|svg|webp|js|mjs|ts|py|sh|yml|yaml|css|html)\b/g, ''); + + // Match snake_case identifiers (bare in prose, backticks, bullet lists, tables, etc.) + for (const match of clean.matchAll(/\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b/g)) { + const name = match[0]; + const invoked = /^(?:\s*\(|`\()/.test(clean.slice(match.index + name.length)); + if (!DATA_IDENTIFIERS.has(name) || invoked) { + names.add(name); + } + } + // Dynamic tool templates cannot be verified against an exact-name allowlist. + if (/\b(?:[a-z]+_)*(?:<[^>]+>|\*)_[a-z_]+\b|\b[a-z]+_\*/.test(line)) { + names.add('[dynamic tool template: spell out exact tool names]'); + } + for (const name of names) { + refs.push({ name, line: index + 1 }); + } + }); + return refs; +} + +export function findSkillFiles(dir) { + if (!fs.existsSync(dir)) return []; + const entries = fs.readdirSync(dir, { withFileTypes: true }); + const files = []; + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + files.push(...findSkillFiles(fullPath)); + } else if (entry.isFile() && entry.name.endsWith('.md')) { + files.push(fullPath); + } + } + return files; +} + +export function checkSkillTools({ root = ROOT, allowlistPath } = {}) { + const allowed = loadAllowlist(allowlistPath); + const skillDirs = [ + path.join(root, 'skills'), + path.join(root, 'packages/claude-directory/skills'), + ].filter(d => fs.existsSync(d)); + + const skillFiles = skillDirs.flatMap(d => findSkillFiles(d)); + const helpFile = path.join(root, 'config/claude-directory/help.md'); + if (fs.existsSync(helpFile) && !skillFiles.includes(helpFile)) { + skillFiles.push(helpFile); + } + + if (skillFiles.length === 0) { + throw new Error('No skill files found to check.'); + } + + const errors = []; + let checkedRefs = 0; + + for (const file of skillFiles) { + const content = fs.readFileSync(file, 'utf8'); + const relPath = path.relative(root, file); + const refs = extractToolReferences(content); + for (const ref of refs) { + checkedRefs++; + if (!allowed.has(ref.name)) { + errors.push(`${relPath}:${ref.line}: referenced tool \`${ref.name}\` is not in scripts/hosted-tools.json`); + } + } + } + + return { errors, skillCount: skillFiles.length, checkedRefs, allowedCount: allowed.size }; +} + +export function main() { + const result = checkSkillTools(); + if (result.errors.length > 0) { + console.error(`Found ${result.errors.length} unapproved tool reference(s):`); + for (const err of result.errors) { + console.error(` ${err}`); + } + process.exitCode = 1; + return; + } + console.log(`Checked ${result.skillCount} skill files (${result.checkedRefs} tool references): all exist in scripts/hosted-tools.json (${result.allowedCount} hosted tools).`); +} + +try { + if (process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) { + main(); + } +} catch { + if (process.argv[1] === fileURLToPath(import.meta.url)) { + main(); + } +} diff --git a/scripts/check-skill-tools.test.js b/scripts/check-skill-tools.test.js new file mode 100644 index 0000000..2360552 --- /dev/null +++ b/scripts/check-skill-tools.test.js @@ -0,0 +1,241 @@ +'use strict'; +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const { spawnSync } = require('node:child_process'); + +test('check-skill-tools.mjs passes on current repository skills and hosted-tools.json', async () => { + const script = path.join(__dirname, 'check-skill-tools.mjs'); + const result = spawnSync(process.execPath, [script], { encoding: 'utf8' }); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Checked \d+ skill files/); + assert.match(result.stdout, /304 hosted tools/); +}); + +test('check-skill-tools.mjs fails when a skill references an unlisted tool', async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-tools-test-')); + try { + fs.mkdirSync(path.join(tmpDir, 'scripts'), { recursive: true }); + fs.mkdirSync(path.join(tmpDir, 'skills/demo'), { recursive: true }); + + // Copy allowlist + fs.copyFileSync( + path.join(__dirname, 'hosted-tools.json'), + path.join(tmpDir, 'scripts/hosted-tools.json') + ); + // Copy script + fs.copyFileSync( + path.join(__dirname, 'check-skill-tools.mjs'), + path.join(tmpDir, 'scripts/check-skill-tools.mjs') + ); + + // Write a skill with an invalid tool + fs.writeFileSync( + path.join(tmpDir, 'skills/demo/SKILL.md'), + '---\nname: demo\ndescription: demo\n---\nCall `unlisted_fake_tool` to do things.\n' + ); + + const result = spawnSync( + process.execPath, + [path.join(tmpDir, 'scripts/check-skill-tools.mjs')], + { cwd: tmpDir, encoding: 'utf8' } + ); + assert.equal(result.status, 1); + assert.match(result.stderr, /referenced tool `unlisted_fake_tool` is not in scripts\/hosted-tools\.json/); + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +}); + +test('check-skill-tools.mjs ignores data identifiers in skills', async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-tools-test-')); + try { + fs.mkdirSync(path.join(tmpDir, 'scripts'), { recursive: true }); + fs.mkdirSync(path.join(tmpDir, 'skills/demo'), { recursive: true }); + + fs.copyFileSync( + path.join(__dirname, 'hosted-tools.json'), + path.join(tmpDir, 'scripts/hosted-tools.json') + ); + fs.copyFileSync( + path.join(__dirname, 'check-skill-tools.mjs'), + path.join(tmpDir, 'scripts/check-skill-tools.mjs') + ); + + // Write a skill with allowed tool and data identifiers + fs.writeFileSync( + path.join(tmpDir, 'skills/demo/SKILL.md'), + '---\nname: demo\ndescription: demo\n---\nCheck `list_connected_accounts` with `utm_source`, `utm_medium`, and `event_id`.\n' + ); + + const result = spawnSync( + process.execPath, + [path.join(tmpDir, 'scripts/check-skill-tools.mjs')], + { cwd: tmpDir, encoding: 'utf8' } + ); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Checked 1 skill files/); + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +}); + +test('extractToolReferences detects unquoted, list, backtick, and explicit tool references', async () => { + const { extractToolReferences } = await import('./check-skill-tools.mjs'); + const content = [ + 'Call list_campaigns before pause_campaign.', + '- list_connected_accounts: verify platforms', + 'Run `pull_meta_ads_performance(days=30, level="ad-set")` for detail.', + 'Use tool:optimize_budget and mcp__synter__get_attribution.', + ].join('\n'); + const refs = extractToolReferences(content); + assert.deepEqual(refs, [ + { name: 'list_campaigns', line: 1 }, + { name: 'pause_campaign', line: 1 }, + { name: 'list_connected_accounts', line: 2 }, + { name: 'pull_meta_ads_performance', line: 3 }, + { name: 'optimize_budget', line: 4 }, + { name: 'get_attribution', line: 4 }, + ]); +}); + +test('extractToolReferences ignores data identifiers unless invoked, and avoids false positives for URLs and files', async () => { + const { extractToolReferences } = await import('./check-skill-tools.mjs'); + const content = [ + 'Use `utm_source`, `utm_medium`, and `event_id` fields.', + 'Call event_id() as a function.', + 'Visit https://synterai.com/privacy_policy and https://synterai.com/terms_of_service.', + 'See rules/brand_safety.md and assets/logo_opaque.png for guidelines.', + 'Read [campaign documentation](docs/campaign_guide.md) or [list_campaigns](docs/list_campaigns.md).', + '', + ].join('\n'); + const refs = extractToolReferences(content); + assert.deepEqual(refs, [ + { name: 'event_id', line: 2 }, + { name: 'list_campaigns', line: 5 }, + ]); +}); + +test('extractToolReferences fails closed on dynamic tool templates', async () => { + const { extractToolReferences } = await import('./check-skill-tools.mjs'); + const content = [ + 'Use `pull__ads_performance` to fetch data.', + 'Run `get_*` for all metrics.', + ].join('\n'); + const refs = extractToolReferences(content); + assert.equal(refs.length, 2); + assert.match(refs[0].name, /dynamic tool template/); + assert.match(refs[1].name, /dynamic tool template/); +}); + +test('check-skill-tools.mjs fails when a skill references an unquoted unlisted tool in prose or lists', async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-tools-unquoted-')); + try { + fs.mkdirSync(path.join(tmpDir, 'scripts'), { recursive: true }); + fs.mkdirSync(path.join(tmpDir, 'skills/demo'), { recursive: true }); + + fs.copyFileSync( + path.join(__dirname, 'hosted-tools.json'), + path.join(tmpDir, 'scripts/hosted-tools.json') + ); + fs.copyFileSync( + path.join(__dirname, 'check-skill-tools.mjs'), + path.join(tmpDir, 'scripts/check-skill-tools.mjs') + ); + + // Skill with unquoted tool in prose and list + fs.writeFileSync( + path.join(tmpDir, 'skills/demo/SKILL.md'), + '---\nname: demo\ndescription: demo\n---\nCall unlisted_prose_tool to run checks.\n- unlisted_list_tool: unlisted bullet tool\n' + ); + + const result = spawnSync( + process.execPath, + [path.join(tmpDir, 'scripts/check-skill-tools.mjs')], + { cwd: tmpDir, encoding: 'utf8' } + ); + assert.equal(result.status, 1); + assert.match(result.stderr, /referenced tool `unlisted_prose_tool` is not in scripts\/hosted-tools\.json/); + assert.match(result.stderr, /referenced tool `unlisted_list_tool` is not in scripts\/hosted-tools\.json/); + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +}); + +test('check-skill-tools.mjs scans config/claude-directory/help.md and reports unlisted tools', async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-tools-help-')); + try { + fs.mkdirSync(path.join(tmpDir, 'scripts'), { recursive: true }); + fs.mkdirSync(path.join(tmpDir, 'skills/demo'), { recursive: true }); + fs.mkdirSync(path.join(tmpDir, 'config/claude-directory'), { recursive: true }); + + fs.copyFileSync( + path.join(__dirname, 'hosted-tools.json'), + path.join(tmpDir, 'scripts/hosted-tools.json') + ); + fs.copyFileSync( + path.join(__dirname, 'check-skill-tools.mjs'), + path.join(tmpDir, 'scripts/check-skill-tools.mjs') + ); + + // Valid root skill + fs.writeFileSync( + path.join(tmpDir, 'skills/demo/SKILL.md'), + '---\nname: demo\ndescription: demo\n---\nUse `list_campaigns`.\n' + ); + // config/claude-directory/help.md with unhosted tool + fs.writeFileSync( + path.join(tmpDir, 'config/claude-directory/help.md'), + '---\nname: help\ndescription: help\n---\nCall unlisted_directory_help_tool to inspect accounts.\n' + ); + + const result = spawnSync( + process.execPath, + [path.join(tmpDir, 'scripts/check-skill-tools.mjs')], + { cwd: tmpDir, encoding: 'utf8' } + ); + assert.equal(result.status, 1); + assert.match(result.stderr, /config\/claude-directory\/help\.md:5: referenced tool `unlisted_directory_help_tool` is not in scripts\/hosted-tools\.json/); + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +}); + +test('check-skill-tools.mjs passes when config/claude-directory/help.md has valid tools and URLs', async () => { + const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'skill-tools-help-pass-')); + try { + fs.mkdirSync(path.join(tmpDir, 'scripts'), { recursive: true }); + fs.mkdirSync(path.join(tmpDir, 'skills/demo'), { recursive: true }); + fs.mkdirSync(path.join(tmpDir, 'config/claude-directory'), { recursive: true }); + + fs.copyFileSync( + path.join(__dirname, 'hosted-tools.json'), + path.join(tmpDir, 'scripts/hosted-tools.json') + ); + fs.copyFileSync( + path.join(__dirname, 'check-skill-tools.mjs'), + path.join(tmpDir, 'scripts/check-skill-tools.mjs') + ); + + fs.writeFileSync( + path.join(tmpDir, 'skills/demo/SKILL.md'), + '---\nname: demo\ndescription: demo\n---\nUse `list_campaigns`.\n' + ); + fs.writeFileSync( + path.join(tmpDir, 'config/claude-directory/help.md'), + '---\nname: help\ndescription: help\n---\nUse list_connected_accounts. See [Privacy](https://synterai.com/privacy) and rules/brand_safety.md.\n' + ); + + const result = spawnSync( + process.execPath, + [path.join(tmpDir, 'scripts/check-skill-tools.mjs')], + { cwd: tmpDir, encoding: 'utf8' } + ); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /Checked 2 skill files/); + } finally { + fs.rmSync(tmpDir, { recursive: true, force: true }); + } +}); diff --git a/scripts/hosted-tools.json b/scripts/hosted-tools.json new file mode 100644 index 0000000..3a47be4 --- /dev/null +++ b/scripts/hosted-tools.json @@ -0,0 +1,306 @@ +[ + "add_keywords", + "add_negative_keywords", + "add_skill", + "angstrom_build_review", + "angstrom_verify_output", + "approve_campaign_plan", + "approve_organic_post", + "attach_audience", + "audit_account_structure", + "audit_campaign_waste", + "audit_llm_crawler_readiness", + "audit_review_site_profiles", + "benchmark_landing_page", + "build_abm_audience", + "build_lookalike_audience", + "cancel_scheduled_post", + "company_intel_get_hiring_signals", + "company_intel_get_profile", + "company_intel_get_signals", + "company_intel_get_tech_stack", + "company_intel_lookup_taxonomy", + "company_intel_search_job_posts", + "company_intel_search_people", + "company_intel_search_teams", + "configure_pixel_destination", + "create_ad_copy", + "create_autonomous_schedule", + "create_campaign_for_audience", + "create_campaign_import", + "create_campaign_plan", + "create_conversion", + "create_document", + "create_embed", + "create_google_doc", + "create_google_file", + "create_google_sheet", + "create_image", + "create_image_asset", + "create_landing_page", + "create_landing_page_variants", + "create_remotion_video", + "create_social_clip", + "create_verified_page_replica", + "create_video_ad", + "delete_audience", + "delete_document", + "design_ad_creatives", + "disable_campaign_guardrail", + "discover_llm_visibility_prompts", + "document_authoring_apply", + "document_authoring_read", + "document_authoring_render", + "draft_organic_post", + "draft_wikipedia_article", + "enable_campaign", + "enrich_contacts", + "execute", + "execute_campaign_plan", + "find_audience_signals", + "find_llm_citation_listicles", + "forecast_campaign", + "forecast_tool_cost", + "ga4_get_conversions", + "ga4_get_properties", + "ga4_get_report", + "generate_image", + "generate_jsonld_schema_markup", + "generate_ugc_ad", + "generate_video", + "generate_voice_ad", + "get_account_changelog", + "get_ad_readback", + "get_attribution", + "get_billing", + "get_billing_status", + "get_campaign_observation", + "get_campaign_plan", + "get_click_attribution", + "get_connection_status", + "get_credit_balance", + "get_daily_spend", + "get_embed", + "get_embed_code", + "get_embeds", + "get_google_file", + "get_gtm_tag", + "get_job_status", + "get_launch_gate_policy", + "get_llm_visibility_overview", + "get_organic_publishing_readiness", + "get_performance", + "get_pixel_destinations", + "get_pixel_health", + "get_plan_execution", + "get_plugin_info", + "get_spend_reconciliation", + "get_tech_intel", + "get_vendor_consumption", + "get_workspaces", + "google_ads_manage_custom_goals", + "growth_discover", + "growth_enrich", + "gtm_get_resources", + "inspect_script", + "klaviyo_create_campaign", + "klaviyo_create_event", + "klaviyo_get_campaign_metrics", + "klaviyo_get_campaigns", + "klaviyo_get_flows", + "klaviyo_get_lists", + "klaviyo_get_templates", + "klaviyo_update_list_profiles", + "linkedin_ads_create_campaign", + "linkedin_ads_create_campaign_group", + "list_ad_accounts", + "list_ad_design_records", + "list_audiences", + "list_autonomous_schedules", + "list_available_scripts", + "list_campaign_guardrails", + "list_campaigns", + "list_connected_accounts", + "list_creative_assets", + "list_embed_purchases", + "list_embed_submissions", + "list_embeds", + "list_event_deliveries", + "list_gtm_containers", + "list_gtm_tags", + "list_llm_visibility_opportunities", + "list_llm_visibility_prompts", + "list_llm_visibility_sightings", + "list_project_audiences", + "list_remotion_templates", + "list_scheduled_posts", + "list_skills", + "load_skill", + "measure_incrementality", + "meta_ads_create_ad", + "optimize_budget", + "pause_campaign", + "prepare_project_audience_sync", + "prospector_add_leads", + "prospector_assign_inboxes_to_campaign", + "prospector_clear_reply_timers", + "prospector_create_campaign", + "prospector_create_reply", + "prospector_dedupe_leads", + "prospector_edit_reply_draft", + "prospector_get_analytics_summary", + "prospector_get_bounced_leads", + "prospector_get_campaign", + "prospector_get_campaign_performance", + "prospector_get_campaigns", + "prospector_get_inbox_health", + "prospector_get_intro_paths", + "prospector_get_leads", + "prospector_get_pending_replies", + "prospector_get_pipeline_summary", + "prospector_get_reply_autosend", + "prospector_get_reply_timers", + "prospector_get_report", + "prospector_get_reports", + "prospector_get_step_performance", + "prospector_get_warm_intros", + "prospector_get_workflows", + "prospector_post_linkedin_comment", + "prospector_post_linkedin_document", + "prospector_reconcile_campaign_leads", + "prospector_regenerate_reply", + "prospector_remove_leads", + "prospector_send_outreach_email", + "prospector_set_campaign_auto_reply", + "prospector_set_reply_fail_open", + "prospector_set_workflow_state", + "prospector_skip_reply", + "prospector_suppress_leads", + "prospector_update_campaign_sequence", + "prospector_update_campaign_settings", + "prospector_update_campaign_status", + "prospector_update_lead_custom_variables", + "prospector_verify_and_push_leads", + "prospector_verify_leads", + "publish_gtm_container", + "publish_landing_page", + "publish_organic_post", + "publish_plan_document", + "publish_skill", + "publish_to_github", + "pull_amazon_ads_performance", + "pull_amazon_dsp_performance", + "pull_cm360_performance", + "pull_criteo_ads_performance", + "pull_dv360_performance", + "pull_freewheel_performance", + "pull_google_ads_performance", + "pull_instacart_ads_performance", + "pull_linkedin_ads_performance", + "pull_linkedin_company_engagement", + "pull_meta_ads_performance", + "pull_microsoft_ads_performance", + "pull_openai_ads_performance", + "pull_pinterest_ads_performance", + "pull_reddit_ads_performance", + "pull_snap_ads_performance", + "pull_spotify_ads_performance", + "pull_target_roundel_performance", + "pull_tiktok_ads_performance", + "pull_trade_desk_performance", + "pull_walmart_ads_performance", + "pull_x_ads_performance", + "read_google_drive_file", + "read_google_sheet", + "recommend_llm_visibility_strategy", + "record_ad_design_feedback", + "reddit_ads_create_ad", + "reddit_ads_create_ad_group", + "reddit_ads_create_campaign", + "reddit_ads_create_post", + "repair_account_structure", + "research_campaign_opportunity", + "run_action", + "run_gaql_query", + "run_launch_preflight", + "run_llm_visibility_scan", + "run_tool", + "schedule_organic_post", + "search_actions", + "send_slack_message", + "set_campaign_guardrail", + "set_embed_crm_destination", + "set_spend_alert", + "setup_custom_domain", + "setup_google_ads_trial_funnel", + "shopify_create_discount", + "shopify_create_web_pixel", + "shopify_create_webhook", + "shopify_get_abandoned_checkouts", + "shopify_get_collections", + "shopify_get_customer_audience", + "shopify_get_customers", + "shopify_get_discount_codes", + "shopify_get_inventory_levels", + "shopify_get_inventory_status", + "shopify_get_orders", + "shopify_get_product_feed", + "shopify_get_product_sales", + "shopify_get_products", + "shopify_get_sales_summary", + "shopify_get_shop", + "shopify_get_webhooks", + "stage_audience_artifact", + "studio_edit_landing_page", + "studio_inspect_landing_page", + "sync_audience", + "sync_wikidata_entity", + "synter_audience", + "synter_audience_cancel_export", + "synter_audience_capacity", + "synter_audience_export", + "synter_audience_export_status", + "synter_audience_query", + "synter_audience_schema", + "synter_onboarding_start", + "synter_onboarding_status", + "synter_signal_audience_export", + "synter_signal_entity_relations", + "synter_signal_entity_resolve", + "synter_signal_trait_search", + "tech_intel_company_to_url", + "tech_intel_get_account_usage", + "tech_intel_get_domain_keywords", + "tech_intel_get_domain_technologies", + "tech_intel_get_sites", + "tech_intel_get_technology_changes", + "tech_intel_get_trust_signals", + "tech_intel_product_search", + "test_creatives", + "tiktok_ads_get_ad_groups", + "tiktok_ads_get_adgroup", + "tiktok_ads_get_ads", + "tiktok_ads_get_campaign", + "tiktok_ads_get_insights", + "tiktok_ads_update_adgroup", + "update_active_workspace", + "update_autonomous_schedule", + "update_campaign_budget", + "update_embed", + "update_google_sheet", + "update_gtm_tag", + "update_gtm_tag_html", + "update_landing_page_html", + "update_landing_page_tracking", + "update_llm_visibility_project", + "update_verified_page_replica", + "upload_creative", + "upload_image", + "upload_landing_page_html", + "upload_library_image", + "upsert_plan_entity", + "validate_organic_post", + "verify_custom_domain", + "verify_pixel_ownership", + "verify_platform_accounts" +] diff --git a/scripts/test_build_packages.py b/scripts/test_build_packages.py index 08daf25..b321b57 100644 --- a/scripts/test_build_packages.py +++ b/scripts/test_build_packages.py @@ -58,7 +58,7 @@ def test_directory_rejects_local_execution_and_unknown_files(self): with self.assertRaises(ValueError): mod.validate_claude_directory(changed) for server in [{'command': 'node'}, {'type': 'http', 'url': 'https://other.example', 'description': 'test'}, - {'type': 'http', 'url': 'https://mcp.synterai.com', 'description': 'test', 'headers': {'x-key': 'fake'}}]: + {'type': 'http', 'url': 'https://mcp.synterai.com/mcp', 'description': 'test', 'headers': {'x-key': 'fake'}}]: with self.subTest(server=server), self.assertRaises(ValueError): mod.validate_claude_directory({**files, '.mcp.json': mod.encoded({'mcpServers': {'synter': server}})}) @@ -99,10 +99,10 @@ def test_directory_generated_source_detects_drift_and_symlinks(self): def test_archives_match_reviewed_rsa_correction_bytes(self): expected = { - 'claude': '72fecb572222d3725acd884f4d7f49a3f5493a2c084d4a4ee201a53a960aee73', - 'claude-directory': 'e313a4ed69ef3e2e80d13c622d102e69d8e6c51cfeb8f0ba13f29b2e0340efc1', - 'openai': '5ab905019791b7f0f71033e19e18042e26ba272b7b2d958aac4ff177a7c0f665', - 'openai-new-draft': '48bbdbedbc5eb96ffacfcd18b339048139ac6f67dbca160e5fd2d13b7682cd87', + 'claude': '09e02d46831992bbfe9b0fbbf162382a7f86afdbea87e94ee47a96d8788f5ddb', + 'claude-directory': '59bf4933b3759a73dc5c67e550a0531954c320c31b2f329216e61e426effec0e', + 'openai': '65e8c79639195e4b42b6d2edebf674fc6934ef151fe9813ed24a8fed1653c222', + 'openai-new-draft': '1b611b4a4ddf6299fc89b357809a3d4136f05f070c355dbe6d8d1b16815a47b5', } # Snapshot after the approved RSA/bidding correction across all hosts. # Update deliberately when reviewed package contents change. diff --git a/scripts/validate-manifests.js b/scripts/validate-manifests.js index a2a246d..27662ac 100644 --- a/scripts/validate-manifests.js +++ b/scripts/validate-manifests.js @@ -115,8 +115,8 @@ if (fs.existsSync(SKILLS_DIR)) { // (d) Client-specific HTTP syntax remains separate from the portable MCP schema. for (const [configPath, expectedUrl] of [ - ['.mcp.json', 'https://mcp.synterai.com'], - ['.cursor-mcp.json', 'https://mcp.synterai.com'], + ['.mcp.json', 'https://mcp.synterai.com/mcp'], + ['.cursor-mcp.json', 'https://mcp.synterai.com/mcp'], ]) { const config = manifests[configPath]; const servers = config && config.mcpServers; @@ -172,7 +172,7 @@ if (openai?.hooks || openai?.apps || fs.existsSync(path.join(REPO_ROOT, '.app.js const portableServer = portableMcp?.mcpServers?.synter; if (portableMcp?.$schema !== 'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json' || Object.keys(portableMcp?.mcpServers || {}).length !== 1 || portableServer?.type !== 'streamable-http' || - portableServer?.url !== 'https://mcp.synterai.com' || + portableServer?.url !== 'https://mcp.synterai.com/mcp' || Object.keys(portableServer || {}).some(key => !['type', 'url'].includes(key))) { errors.push('mcp.json: expected portable HTTP transport and OAuth DCR without credentials'); } diff --git a/scripts/validate-manifests.test.js b/scripts/validate-manifests.test.js index 9388bfa..73afbb5 100644 --- a/scripts/validate-manifests.test.js +++ b/scripts/validate-manifests.test.js @@ -74,7 +74,7 @@ for (const [name, filename, mutate, error] of [ ['missing public logo', 'plugin.json', m => { m.extensions['com.openai'].interface.logo = './assets/missing.png'; }, /missing packaged logo/], ['public lifecycle hook', 'plugin.json', m => { m.extensions['com.openai'].hooks = './hooks/hooks.json'; }, /cannot declare hooks/], ['static authentication secret', 'mcp.json', m => { m.mcpServers.synter.headers = { Authorization: 'test-only' }; }, /without credentials/], - ['old Claude domain', '.mcp.json', m => { m.mcpServers.synter.url = 'https://mcp.syntermedia.ai'; }, /expected a single Synter HTTP server/], + ['wrong MCP url', '.mcp.json', m => { m.mcpServers.synter.url = 'https://mcp.synterai.com'; }, /expected a single Synter HTTP server/], ]) { test(`rejects ${name}`, t => { const repo = fixture(t); diff --git a/sdk/README.md b/sdk/README.md index 02a690c..52fcb16 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -8,7 +8,7 @@ npm install node synter-agent.mjs "/synter:report last 7 days" ``` -Use the host SDK’s supported Claude authentication. Synter uses the plugin’s browser OAuth connection at `https://mcp.synterai.com`. Establish that connection interactively in the host environment first. An unattended process cannot complete a browser prompt; if the host does not reuse the authorized session, run the task interactively. OAuth session reuse depends on the host and must be verified before scheduling this runner. +Use the host SDK’s supported Claude authentication. Synter uses the plugin’s browser OAuth connection at `https://mcp.synterai.com/mcp` (`https://mcp.syntermedia.ai/mcp` is supported as a documented legacy alias). Establish that connection interactively in the host environment first. An unattended process cannot complete a browser prompt; if the host does not reuse the authorized session, run the task interactively. OAuth session reuse depends on the host and must be verified before scheduling this runner. The runner permits the explicitly listed read tools and blocks other Synter tools by default. It also blocks local write and shell tools. Review `synter-agent.mjs` before use. The existing `--allow-writes` option removes the runner’s mutation guard; campaign instructions still require the user’s explicit approval of the action scope. Prefer interactive use when campaign changes need review. diff --git a/skills/quickstart/SKILL.md b/skills/quickstart/SKILL.md index 8659bfd..a04a04f 100644 --- a/skills/quickstart/SKILL.md +++ b/skills/quickstart/SKILL.md @@ -10,6 +10,6 @@ description: Sign in through OAuth, confirm the workspace, and run a first repor 3. For connected GA4 accounts, use `ga4_get_properties`, then `ga4_get_report` with the selected property and requested period. Use the tool’s returned schema for parameters. 4. Offer a first task: a **report**, a **launch** plan, an **audience** review, or **ad-copy-generation**. Do not claim access to accounts or data that the tools did not return. -The plugin connects to the hosted Synter MCP server over OAuth. Cursor uses https://mcp.synterai.com; Claude uses https://mcp.synterai.com. Both require a client that supports remote MCP and browser OAuth. +The plugin connects to the hosted Synter MCP server over OAuth at https://mcp.synterai.com/mcp (with https://mcp.syntermedia.ai/mcp supported as a documented legacy alias). Both Cursor and Claude require a client that supports remote MCP and browser OAuth. Reads do not require approval. Show the exact scope and obtain explicit approval before account mutations or spend changes. More help: **help** or https://synterai.com/contact.