Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .cursor-mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"mcpServers": {
"synter": {
"type": "http",
"url": "https://mcp.synterai.com"
"url": "https://mcp.synterai.com/mcp"
}
}
}
2 changes: 2 additions & 0 deletions .github/workflows/directory-tools.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
3 changes: 3 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
}
Expand Down
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions CLAUDE_COMMUNITY_SUBMISSION.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 |
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion config/claude-directory/README.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
2 changes: 1 addition & 1 deletion mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"mcpServers": {
"synter": {
"type": "streamable-http",
"url": "https://mcp.synterai.com"
"url": "https://mcp.synterai.com/mcp"
}
}
}
2 changes: 1 addition & 1 deletion packages/claude-directory/.mcp.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
}
Expand Down
2 changes: 1 addition & 1 deletion packages/claude-directory/README.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
2 changes: 1 addition & 1 deletion packages/claude-directory/skills/quickstart/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
2 changes: 1 addition & 1 deletion scripts/build-packages.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
4 changes: 2 additions & 2 deletions scripts/check-directory-tools.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [];
Expand Down Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion scripts/check-directory-tools.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 });
Expand Down
140 changes: 140 additions & 0 deletions scripts/check-skill-tools.mjs
Original file line number Diff line number Diff line change
@@ -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__<tool> or tool:<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();
}
}
Loading
Loading