From 18b4ef5a8a19c87bc6b16fbdba2af789675d3d6e Mon Sep 17 00:00:00 2001 From: Joel Horwitz Date: Mon, 2 Nov 2026 08:42:41 -0800 Subject: [PATCH 1/3] fix: scrub plugin configs, point MCP to /mcp, add hosted tool check - Point Claude (.mcp.json), Cursor (.cursor-mcp.json), and portable (mcp.json) configs at https://mcp.syntermedia.ai/mcp over browser OAuth. - Add scripts/hosted-tools.json (304 tools) from ppc-backend and docs. - Add scripts/check-skill-tools.mjs and wire it into directory-tools and validate CI workflows to verify skill tool references. - State pricing (/bin/bash.25 per verified write, 0% of ad spend) and 30+ ad platforms across documentation and metadata. Amp-Thread-ID: https://ampcode.com/threads/T-01a19d0d-f546-741a-a3b6-fa9df5406a2f Co-authored-by: Amp --- .cursor-mcp.json | 2 +- .github/workflows/directory-tools.yml | 2 + .github/workflows/validate.yml | 3 + .mcp.json | 2 +- CHANGELOG.md | 6 + CLAUDE_COMMUNITY_SUBMISSION.md | 4 +- README.md | 6 +- SECURITY.md | 2 +- config/claude-directory/README.md | 2 +- mcp.json | 2 +- packages/claude-directory/.mcp.json | 2 +- packages/claude-directory/README.md | 2 +- .../skills/quickstart/SKILL.md | 2 +- plugin.json | 2 +- scripts/build-packages.py | 2 +- scripts/check-directory-tools.js | 4 +- scripts/check-directory-tools.test.js | 2 +- scripts/check-skill-tools.mjs | 117 +++++++ scripts/check-skill-tools.test.js | 83 +++++ scripts/hosted-tools.json | 306 ++++++++++++++++++ scripts/test_build_packages.py | 10 +- scripts/validate-manifests.js | 6 +- scripts/validate-manifests.test.js | 2 +- sdk/README.md | 2 +- skills/quickstart/SKILL.md | 2 +- 25 files changed, 546 insertions(+), 29 deletions(-) create mode 100755 scripts/check-skill-tools.mjs create mode 100644 scripts/check-skill-tools.test.js create mode 100644 scripts/hosted-tools.json diff --git a/.cursor-mcp.json b/.cursor-mcp.json index b865a6c..ebf1bc2 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.syntermedia.ai/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..296644e 100644 --- a/.mcp.json +++ b/.mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.synterai.com", + "url": "https://mcp.syntermedia.ai/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..9dbbbd0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## [1.2.1] - Unreleased +- Canonicalize MCP server URL to `https://mcp.syntermedia.ai/mcp` across Claude, + Cursor, and portable OpenAI configurations with browser OAuth. +- 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..c935d79 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.syntermedia.ai/mcp`. 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.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..9dea649 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,8 +58,8 @@ 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.syntermedia.ai/mcp` | +| Claude | `.mcp.json`, discovered by the Claude plugin | `https://mcp.syntermedia.ai/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). diff --git a/SECURITY.md b/SECURITY.md index fdaddff..1d84ac6 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.syntermedia.ai/mcp` 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..0b8a1ce 100644 --- a/mcp.json +++ b/mcp.json @@ -3,7 +3,7 @@ "mcpServers": { "synter": { "type": "streamable-http", - "url": "https://mcp.synterai.com" + "url": "https://mcp.syntermedia.ai/mcp" } } } diff --git a/packages/claude-directory/.mcp.json b/packages/claude-directory/.mcp.json index c3ae094..296644e 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.syntermedia.ai/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..1f66ca7 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.syntermedia.ai/mcp. 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..056d60f 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.syntermedia.ai/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..5ce9042 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.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.syntermedia.ai/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..f307070 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.syntermedia.ai/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..a479278 --- /dev/null +++ b/scripts/check-skill-tools.mjs @@ -0,0 +1,117 @@ +#!/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) => { + // Match explicit syntax: mcp__synter__ or tool: + for (const match of line.matchAll(/\bmcp__[a-zA-Z0-9_-]+?__([a-z][a-z0-9_]+)|\btool:([a-z][a-z0-9_]+)/g)) { + const toolName = match[1] || match[2]; + refs.push({ name: toolName, line: index + 1 }); + } + // Match backticked snake_case identifiers + for (const match of line.matchAll(/`([a-z][a-z0-9]*(?:_[a-z0-9]+)+)`/g)) { + const name = match[1]; + if (!DATA_IDENTIFIERS.has(name)) { + 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)); + 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..3607183 --- /dev/null +++ b/scripts/check-skill-tools.test.js @@ -0,0 +1,83 @@ +'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 }); + } +}); 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..637161d 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.syntermedia.ai/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': '9a15f7c09a26e88fccaca04cfd90f0bb124854d2c880bbf23682b7a919463eb1', + 'claude-directory': '2aec9e6a6c5814cd72cab38b3078f6a31731e013b7376fe96bc6e026e0c623b0', + 'openai': 'da30dd604f66ed579741ab7798018cd6f8b8cb09ff5cd8c2094cdf3d28611257', + 'openai-new-draft': '7045f252e7251a357b09dd3c8b5e67550c8c7527865406cd1673a46e1b22e1b8', } # 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..e95bd15 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.syntermedia.ai/mcp'], + ['.cursor-mcp.json', 'https://mcp.syntermedia.ai/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.syntermedia.ai/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..43eddb3 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.syntermedia.ai/mcp`. 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..1f66ca7 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.syntermedia.ai/mcp. 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. From 9e6bd7eba48e09f5adcf0a42c51a78f390a84bab Mon Sep 17 00:00:00 2001 From: Joel Horwitz Date: Tue, 3 Nov 2026 15:12:05 +0000 Subject: [PATCH 2/3] fix: canonicalize hosted MCP endpoint to https://mcp.synterai.com/mcp - Set canonical hosted MCP server URL to https://mcp.synterai.com/mcp across manifests, configs (.mcp.json, .cursor-mcp.json, mcp.json, packages/claude-directory/.mcp.json), documentation, and SDK. - Retain mcp.syntermedia.ai as a documented legacy alias in README, SECURITY, submission docs, and validator endpoints. - Update packaging and manifest validation scripts and package archive SHA-256 digests. - Verified up-to-date with origin/main (85be651). Co-authored-by: Amp Amp-Thread-ID: https://ampcode.com/threads/T-01a1a1e7-f9f8-7464-a4d2-5d82bd77b28a --- .cursor-mcp.json | 2 +- .mcp.json | 2 +- CHANGELOG.md | 5 +++-- CLAUDE_COMMUNITY_SUBMISSION.md | 4 ++-- README.md | 6 +++--- SECURITY.md | 2 +- mcp.json | 2 +- packages/claude-directory/.mcp.json | 2 +- packages/claude-directory/skills/quickstart/SKILL.md | 2 +- scripts/build-packages.py | 2 +- scripts/check-directory-tools.js | 4 ++-- scripts/check-directory-tools.test.js | 2 +- scripts/test_build_packages.py | 10 +++++----- scripts/validate-manifests.js | 6 +++--- sdk/README.md | 2 +- skills/quickstart/SKILL.md | 2 +- 16 files changed, 28 insertions(+), 27 deletions(-) diff --git a/.cursor-mcp.json b/.cursor-mcp.json index ebf1bc2..28d2e6c 100644 --- a/.cursor-mcp.json +++ b/.cursor-mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.syntermedia.ai/mcp" + "url": "https://mcp.synterai.com/mcp" } } } diff --git a/.mcp.json b/.mcp.json index 296644e..c5f758a 100644 --- a/.mcp.json +++ b/.mcp.json @@ -2,7 +2,7 @@ "mcpServers": { "synter": { "type": "http", - "url": "https://mcp.syntermedia.ai/mcp", + "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 9dbbbd0..e67a1d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,9 @@ ## [1.2.1] - Unreleased -- Canonicalize MCP server URL to `https://mcp.syntermedia.ai/mcp` across Claude, - Cursor, and portable OpenAI configurations with browser OAuth. +- 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) diff --git a/CLAUDE_COMMUNITY_SUBMISSION.md b/CLAUDE_COMMUNITY_SUBMISSION.md index c935d79..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 and Cursor connect to `https://mcp.syntermedia.ai/mcp`. 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/mcp` | +| 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 9dea649..9dc731b 100644 --- a/README.md +++ b/README.md @@ -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.syntermedia.ai/mcp` | -| Claude | `.mcp.json`, discovered by the Claude plugin | `https://mcp.syntermedia.ai/mcp` | +| 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 1d84ac6..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.syntermedia.ai/mcp` 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/mcp.json b/mcp.json index 0b8a1ce..e7390da 100644 --- a/mcp.json +++ b/mcp.json @@ -3,7 +3,7 @@ "mcpServers": { "synter": { "type": "streamable-http", - "url": "https://mcp.syntermedia.ai/mcp" + "url": "https://mcp.synterai.com/mcp" } } } diff --git a/packages/claude-directory/.mcp.json b/packages/claude-directory/.mcp.json index 296644e..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.syntermedia.ai/mcp", + "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/skills/quickstart/SKILL.md b/packages/claude-directory/skills/quickstart/SKILL.md index 1f66ca7..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 at https://mcp.syntermedia.ai/mcp. Both Cursor and Claude 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/scripts/build-packages.py b/scripts/build-packages.py index 056d60f..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.syntermedia.ai/mcp' + 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 5ce9042..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.syntermedia.ai/mcp', 'https://mcp.syntermedia.ai', 'https://mcp.synterai.com']); +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.syntermedia.ai/mcp', 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 f307070..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.syntermedia.ai/mcp'); + 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/test_build_packages.py b/scripts/test_build_packages.py index 637161d..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.syntermedia.ai/mcp', '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': '9a15f7c09a26e88fccaca04cfd90f0bb124854d2c880bbf23682b7a919463eb1', - 'claude-directory': '2aec9e6a6c5814cd72cab38b3078f6a31731e013b7376fe96bc6e026e0c623b0', - 'openai': 'da30dd604f66ed579741ab7798018cd6f8b8cb09ff5cd8c2094cdf3d28611257', - 'openai-new-draft': '7045f252e7251a357b09dd3c8b5e67550c8c7527865406cd1673a46e1b22e1b8', + '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 e95bd15..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.syntermedia.ai/mcp'], - ['.cursor-mcp.json', 'https://mcp.syntermedia.ai/mcp'], + ['.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.syntermedia.ai/mcp' || + 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/sdk/README.md b/sdk/README.md index 43eddb3..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.syntermedia.ai/mcp`. 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 1f66ca7..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 at https://mcp.syntermedia.ai/mcp. Both Cursor and Claude 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. From e60faaa45b4aca2a41043445547da112f35bc155 Mon Sep 17 00:00:00 2001 From: Joel Horwitz Date: Wed, 4 Nov 2026 11:47:25 -0800 Subject: [PATCH 3/3] fix: detect unquoted tool references and scan directory help in check-skill-tools - Update scripts/check-skill-tools.mjs to detect unquoted tool references in prose, lists, backticks, and function calls without false positives from URLs, link targets, or file extensions. - Scan config/claude-directory/help.md alongside skill directories. - Fail closed on dynamic tool templates. - Add unit tests for extractToolReferences and CLI fixtures for unquoted prose/list tools and config/claude-directory/help.md scanning. - Addresses CodeRabbit r4445159218 on PR #26. Amp-Thread-ID: https://ampcode.com/threads/T-01a1a808-f966-70f8-a96e-598a8daccfb0 Co-authored-by: Amp --- scripts/check-skill-tools.mjs | 39 ++++++-- scripts/check-skill-tools.test.js | 158 ++++++++++++++++++++++++++++++ 2 files changed, 189 insertions(+), 8 deletions(-) diff --git a/scripts/check-skill-tools.mjs b/scripts/check-skill-tools.mjs index a479278..91c94b6 100755 --- a/scripts/check-skill-tools.mjs +++ b/scripts/check-skill-tools.mjs @@ -32,18 +32,36 @@ 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-z][a-z0-9_]+)|\btool:([a-z][a-z0-9_]+)/g)) { - const toolName = match[1] || match[2]; - refs.push({ name: toolName, line: index + 1 }); + 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]); } - // Match backticked snake_case identifiers - for (const match of line.matchAll(/`([a-z][a-z0-9]*(?:_[a-z0-9]+)+)`/g)) { - const name = match[1]; - if (!DATA_IDENTIFIERS.has(name)) { - refs.push({ name, line: index + 1 }); + // 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; } @@ -71,6 +89,11 @@ export function checkSkillTools({ root = ROOT, allowlistPath } = {}) { ].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.'); } diff --git a/scripts/check-skill-tools.test.js b/scripts/check-skill-tools.test.js index 3607183..2360552 100644 --- a/scripts/check-skill-tools.test.js +++ b/scripts/check-skill-tools.test.js @@ -81,3 +81,161 @@ test('check-skill-tools.mjs ignores data identifiers in skills', async () => { 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 }); + } +});