@lightcone-ai/daemon 0.11.0 → 0.13.0

package/mcp-servers/official/ai-image-gen/index.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const SOURCE_RISK = 'untrusted';
+
+const DOUBAO_DEFAULT_BASE_URL = 'https://ark.cn-beijing.volces.com/api/v3';
+const DALLE_DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+
+const DOUBAO_API_KEY = String(process.env.DOUBAO_API_KEY ?? '').trim();
+const DOUBAO_BASE_URL = String(process.env.DOUBAO_BASE_URL ?? DOUBAO_DEFAULT_BASE_URL).trim();
+const DOUBAO_IMAGE_MODEL = String(process.env.DOUBAO_IMAGE_MODEL ?? 'doubao-seedream-3-0-t2i-250415').trim();
+
+const DALLE_API_KEY = String(process.env.DALL_E_API_KEY ?? process.env.OPENAI_API_KEY ?? '').trim();
+const DALLE_BASE_URL = String(process.env.DALL_E_BASE_URL ?? process.env.OPENAI_BASE_URL ?? DALLE_DEFAULT_BASE_URL).trim();
+const DALLE_IMAGE_MODEL = String(process.env.DALL_E_IMAGE_MODEL ?? 'gpt-image-1').trim();
+
+const REQUEST_TIMEOUT_MS = clampInt(process.env.AI_IMAGE_GEN_TIMEOUT_MS, 1000, 60000, 20000);
+
+function clampInt(value, min, max, fallback) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(n)));
+}
+
+function joinUrl(baseUrl, path) {
+  const trimmedBase = String(baseUrl ?? '').trim();
+  const normalizedBase = trimmedBase.endsWith('/') ? trimmedBase.slice(0, -1) : trimmedBase;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${normalizedBase}${normalizedPath}`;
+}
+
+function parseSize(raw) {
+  const text = String(raw ?? '1024x1024').trim().toLowerCase();
+  const match = text.match(/^(\d{2,4})x(\d{2,4})$/);
+  if (!match) return { size: '1024x1024', width: 1024, height: 1024 };
+  const width = clampInt(match[1], 64, 2048, 1024);
+  const height = clampInt(match[2], 64, 2048, 1024);
+  return { size: `${width}x${height}`, width, height };
+}
+
+function hashString(text) {
+  let hash = 2166136261;
+  const raw = String(text ?? '');
+  for (let i = 0; i < raw.length; i += 1) {
+    hash ^= raw.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+function parseJsonMaybe(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+async function postJson(url, headers, body) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    const payload = parseJsonMaybe(text) ?? { raw: text.slice(0, 600) };
+    if (!res.ok) {
+      throw new Error(`http_${res.status}:${payload?.error?.message ?? text.slice(0, 200)}`);
+    }
+    return payload;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function toImageList(payload) {
+  const rows = Array.isArray(payload?.data) ? payload.data : [];
+  return rows
+    .map((row, index) => {
+      const url = String(row?.url ?? '').trim();
+      const b64 = String(row?.b64_json ?? '').trim();
+      const imageUrl = url || (b64 ? `data:image/png;base64,${b64}` : '');
+      if (!imageUrl) return null;
+      return {
+        id: String(row?.id ?? `img-${index + 1}`),
+        url: imageUrl,
+        revised_prompt: String(row?.revised_prompt ?? '').trim() || null,
+        source_risk: SOURCE_RISK,
+      };
+    })
+    .filter(Boolean);
+}
+
+async function generateOpenAiCompatible({
+  provider,
+  apiKey,
+  baseUrl,
+  model,
+  prompt,
+  size,
+  n,
+  quality,
+  style,
+}) {
+  const payload = {
+    model,
+    prompt,
+    size,
+    n,
+    response_format: 'url',
+  };
+  if (quality) payload.quality = quality;
+  if (style) payload.style = style;
+
+  const data = await postJson(
+    joinUrl(baseUrl, '/images/generations'),
+    {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    payload
+  );
+
+  const images = toImageList(data);
+  if (images.length === 0) {
+    throw new Error(`${provider}_empty_images`);
+  }
+
+  return {
+    provider,
+    model,
+    images,
+    raw: data,
+  };
+}
+
+function providerOrder(requestedProvider) {
+  const requested = String(requestedProvider ?? 'auto').trim().toLowerCase();
+  if (requested === 'doubao') return ['doubao'];
+  if (requested === 'dall-e' || requested === 'dalle') return ['dall-e'];
+  return ['doubao', 'dall-e'];
+}
+
+function getProviderCredential(provider) {
+  if (provider === 'doubao') {
+    return {
+      apiKey: DOUBAO_API_KEY,
+      baseUrl: DOUBAO_BASE_URL,
+      model: DOUBAO_IMAGE_MODEL,
+    };
+  }
+  return {
+    apiKey: DALLE_API_KEY,
+    baseUrl: DALLE_BASE_URL,
+    model: DALLE_IMAGE_MODEL,
+  };
+}
+
+function buildMockImages({ prompt, size, n }) {
+  const count = clampInt(n, 1, 4, 1);
+  const parsed = parseSize(size);
+  const images = [];
+
+  for (let i = 0; i < count; i += 1) {
+    const seed = hashString(`${prompt}|${parsed.size}|${i + 1}`);
+    images.push({
+      id: `mock-${i + 1}`,
+      url: `https://picsum.photos/seed/lightcone-ai-${seed}/${parsed.width}/${parsed.height}`,
+      revised_prompt: null,
+      source_risk: SOURCE_RISK,
+    });
+  }
+
+  return images;
+}
+
+async function generateImages(input) {
+  const prompt = String(input.prompt ?? '').trim();
+  if (!prompt) throw new Error('prompt_required');
+
+  const parsedSize = parseSize(input.size);
+  const n = clampInt(input.count, 1, 4, 1);
+  const quality = input.quality ? String(input.quality).trim() : '';
+  const style = input.style ? String(input.style).trim() : '';
+
+  const attempts = providerOrder(input.provider);
+  const errors = [];
+
+  for (const provider of attempts) {
+    const credential = getProviderCredential(provider);
+    if (!credential.apiKey) {
+      errors.push(`${provider}_missing_api_key`);
+      continue;
+    }
+    try {
+      const generated = await generateOpenAiCompatible({
+        provider,
+        apiKey: credential.apiKey,
+        baseUrl: credential.baseUrl,
+        model: credential.model,
+        prompt,
+        size: parsedSize.size,
+        n,
+        quality,
+        style,
+      });
+
+      return {
+        provider_requested: String(input.provider ?? 'auto').trim().toLowerCase() || 'auto',
+        provider_used: generated.provider,
+        model_used: generated.model,
+        size: parsedSize.size,
+        prompt,
+        images: generated.images,
+        source_risk: SOURCE_RISK,
+        fallback_reason: null,
+        timestamp: new Date().toISOString(),
+      };
+    } catch (error) {
+      errors.push(`${provider}_error:${error.message}`);
+    }
+  }
+
+  return {
+    provider_requested: String(input.provider ?? 'auto').trim().toLowerCase() || 'auto',
+    provider_used: 'mock',
+    model_used: 'mock-image-provider',
+    size: parsedSize.size,
+    prompt,
+    images: buildMockImages({ prompt, size: parsedSize.size, n }),
+    source_risk: SOURCE_RISK,
+    fallback_reason: errors.length > 0 ? errors[0] : 'no_provider_available',
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function toolError(error) {
+  return {
+    isError: true,
+    content: [{ type: 'text', text: `Error: ${error.message}` }],
+  };
+}
+
+const server = new McpServer({ name: 'official-ai-image-gen', version: '0.1.0' });
+
+server.tool(
+  'ai_image_gen',
+  'Generate AI images and return URL list with source_risk=untrusted.',
+  {
+    prompt: z.string().min(1).describe('Image generation prompt.'),
+    provider: z.enum(['auto', 'doubao', 'dall-e']).optional().describe('Image provider. auto = doubao first, then dall-e.'),
+    size: z.string().optional().describe('Image size, e.g. 1024x1024.'),
+    count: z.number().int().min(1).max(4).optional().describe('How many images to generate, default 1.'),
+    quality: z.string().optional().describe('Provider-specific quality, e.g. hd/standard.'),
+    style: z.string().optional().describe('Provider-specific style option.'),
+  },
+  async (input) => {
+    try {
+      const payload = await generateImages(input);
+      return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+      };
+    } catch (error) {
+      return toolError(error);
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error('[official-ai-image-gen] MCP Server started');

package/mcp-servers/official/ai-image-gen/manifest.json

@@ -0,0 +1,19 @@
+{
+  "id": "ai-image-gen",
+  "name": "Official AI Image Gen MCP",
+  "version": "0.1.0",
+  "runtime": "node",
+  "entrypoint": "index.js",
+  "tool_declarations": [
+    { "name": "ai_image_gen", "classification": "cacheable" }
+  ],
+  "smoke_test": {
+    "tool": "ai_image_gen",
+    "arguments": {
+      "prompt": "简洁风格的蓝色科技封面，留白，16:9",
+      "provider": "auto",
+      "size": "1024x1024",
+      "count": 1
+    }
+  }
+}

package/mcp-servers/official/audience-research/index.js

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+import { z } from 'zod';
+import { startFixtureServer } from '../../official-common/server.js';
+
+const FIXTURE_META = Object.freeze({
+  mode: 'fixture',
+  as_of: '2026-04-29',
+  capability: 'audience-research',
+  disclaimer: 'Audience profile is estimated from fixture fan snapshots + public benchmark assumptions, not live platform BI exports.',
+});
+
+const PLATFORM_ALIAS = Object.freeze({
+  xiaohongshu: 'xhs',
+  redbook: 'xhs',
+  douyin: 'douyin',
+  tiktok_cn: 'douyin',
+  wechat: 'wechat-mp',
+  wechat_mp: 'wechat-mp',
+  wechatmp: 'wechat-mp',
+  gzh: 'wechat-mp',
+  '\u516c\u4f17\u53f7': 'wechat-mp',
+});
+
+const PLATFORM_BENCHMARKS = Object.freeze({
+  xhs: Object.freeze({
+    default_audience: {
+      age_range: '25-34',
+      gender_skew: '\u5973\u6027\u4e3b\u5bfc',
+      geo_focus: ['\u4e0a\u6d77', '\u676d\u5dde', '\u6df1\u5733', '\u5317\u4eac'],
+      occupation_tags: ['\u767d\u9886', '\u81ea\u7531\u804c\u4e1a', '\u5b66\u751f'],
+      pain_points: ['\u9009\u9898\u540c\u8d28\u5316', '\u7b14\u8bb0\u8f6c\u5316\u4f4e', '\u62cd\u6444\u6267\u884c\u6210\u672c\u9ad8'],
+      aspirations: ['\u7a33\u5b9a\u6da8\u7c89', '\u5efa\u7acb\u4e13\u4e1a\u4eba\u8bbe', '\u83b7\u5f97\u54c1\u724c\u5408\u4f5c'],
+    },
+    pools: {
+      cities: ['\u4e0a\u6d77', '\u676d\u5dde', '\u82cf\u5dde', '\u6df1\u5733', '\u6210\u90fd', '\u5317\u4eac', '\u5e7f\u5dde'],
+      occupations: ['\u767d\u9886', '\u5185\u5bb9\u8fd0\u8425', '\u8bbe\u8ba1\u5e08', '\u5b66\u751f', '\u81ea\u7531\u804c\u4e1a'],
+      pain_points: ['\u9009\u9898\u540c\u8d28\u5316', '\u5728\u7ebf\u7d22\u5c11', '\u66dd\u5149\u4e0d\u7a33\u5b9a', '\u62cd\u6444\u6548\u7387\u4f4e'],
+      aspirations: ['\u589e\u52a0\u54c1\u724c\u4fe1\u4efb', '\u63d0\u9ad8\u79c1\u57df\u6210\u4ea4', '\u5f62\u6210\u56fa\u5b9a\u4eba\u8bbe', '\u5185\u5bb9\u53ef\u590d\u7528'],
+      female_ratio: 0.68,
+      age_peak: 29,
+    },
+  }),
+  douyin: Object.freeze({
+    default_audience: {
+      age_range: '18-34',
+      gender_skew: '\u5747\u8861',
+      geo_focus: ['\u5317\u4eac', '\u5e7f\u5dde', '\u6210\u90fd', '\u6b66\u6c49'],
+      occupation_tags: ['\u5e74\u8f7b\u767d\u9886', '\u5b66\u751f', '\u4e2a\u4f53\u7ecf\u8425\u8005'],
+      pain_points: ['\u5b8c\u64ad\u7387\u4e0d\u7a33\u5b9a', '\u811a\u672c\u751f\u786c', '\u8d77\u53f7\u6210\u672c\u9ad8'],
+      aspirations: ['\u7206\u6b3e\u7387\u63d0\u5347', '\u4f18\u5316\u8d26\u53f7\u6807\u7b7e', '\u83b7\u5f97\u5546\u5355\u7ebf\u7d22'],
+    },
+    pools: {
+      cities: ['\u5317\u4eac', '\u5e7f\u5dde', '\u6df1\u5733', '\u91cd\u5e86', '\u6210\u90fd', '\u897f\u5b89', '\u957f\u6c99'],
+      occupations: ['\u5b66\u751f', '\u9500\u552e', '\u5e74\u8f7b\u767d\u9886', '\u4e3b\u64ad', '\u4e2a\u4f53\u7ecf\u8425\u8005'],
+      pain_points: ['\u5b8c\u64ad\u7387\u4e0d\u7a33\u5b9a', '\u8bc4\u8bba\u8f6c\u5316\u4f4e', '\u7d20\u6750\u7f3a\u4e4f', '\u66dd\u5149\u6ce2\u52a8\u5927'],
+      aspirations: ['\u63d0\u9ad8\u81ea\u7136\u6d41\u91cf', '\u589e\u52a0\u76f4\u64ad\u8fdb\u623f', '\u7a33\u5b9a\u7c89\u4e1d\u7c98\u6027', '\u63d0\u5347\u8d26\u53f7\u6743\u91cd'],
+      female_ratio: 0.52,
+      age_peak: 27,
+    },
+  }),
+  'wechat-mp': Object.freeze({
+    default_audience: {
+      age_range: '25-44',
+      gender_skew: '\u5747\u8861',
+      geo_focus: ['\u5317\u4eac', '\u4e0a\u6d77', '\u5e7f\u5dde', '\u6df1\u5733'],
+      occupation_tags: ['\u804c\u573a\u7ba1\u7406\u8005', '\u4ea7\u54c1\u7ecf\u7406', '\u4e2d\u5c0f\u4f01\u4e1a\u4e3b'],
+      pain_points: ['\u9605\u8bfb\u6253\u5f00\u7387\u4e0b\u6ed1', '\u6587\u7ae0\u5b8c\u8bfb\u7387\u4f4e', '\u79c1\u57df\u8f6c\u5316\u65ad\u5c42'],
+      aspirations: ['\u5efa\u7acb\u7a33\u5b9a\u793e\u7fa4', '\u63d0\u9ad8\u590d\u8d2d\u7387', '\u63d0\u9ad8\u4e13\u4e1a\u5f71\u54cd\u529b'],
+    },
+    pools: {
+      cities: ['\u5317\u4eac', '\u4e0a\u6d77', '\u6df1\u5733', '\u5e7f\u5dde', '\u676d\u5dde', '\u6b66\u6c49'],
+      occupations: ['\u804c\u573a\u7ba1\u7406\u8005', '\u4ea7\u54c1\u7ecf\u7406', '\u4f01\u4e1a\u670d\u52a1', '\u8fd0\u8425\u8d1f\u8d23\u4eba', '\u4e2d\u5c0f\u4f01\u4e1a\u4e3b'],
+      pain_points: ['\u9605\u8bfb\u6253\u5f00\u7387\u4e0b\u6ed1', '\u9009\u9898\u8001\u5316', '\u9500\u552e\u627f\u63a5\u65ad\u5c42', '\u66f4\u65b0\u8282\u594f\u4e0d\u7a33\u5b9a'],
+      aspirations: ['\u63d0\u5347\u4e13\u4e1a\u8ba4\u77e5', '\u589e\u5f3a\u79c1\u57df\u8f6c\u5316', '\u5b9e\u73b0\u8fde\u8f7d\u5316\u8f93\u51fa', '\u5f62\u6210\u9ad8\u4ef7\u503c\u54a8\u8be2\u7ebf\u7d22'],
+      female_ratio: 0.5,
+      age_peak: 33,
+    },
+  }),
+});
+
+const CSV_FIELD_ALIASES = Object.freeze({
+  age: 'age',
+  age_value: 'age',
+  age_range: 'age',
+  gender: 'gender',
+  sex: 'gender',
+  city: 'city',
+  geo: 'city',
+  location: 'city',
+  occupation: 'occupation',
+  job: 'occupation',
+  pain_point: 'pain_point',
+  painpoint: 'pain_point',
+  challenge: 'pain_point',
+  aspiration: 'aspiration',
+  goal: 'aspiration',
+});
+
+function normalizePlatform(value, accountId = '') {
+  const raw = String(value ?? '').trim().toLowerCase();
+  if (raw) return PLATFORM_ALIAS[raw] ?? raw;
+
+  const id = String(accountId ?? '').toLowerCase();
+  if (id.includes('douyin')) return 'douyin';
+  if (id.includes('wechat') || id.includes('gzh') || id.includes('mp')) return 'wechat-mp';
+  return 'xhs';
+}
+
+function clampInt(value, min, max, fallback) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(min, Math.min(max, Math.trunc(n)));
+}
+
+function deterministicRatio(seed, salt) {
+  const text = `${seed}#${salt}`;
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) / 4294967295;
+}
+
+function parseAge(value) {
+  const text = String(value ?? '').trim();
+  if (!text) return null;
+  const num = Number(text);
+  if (Number.isFinite(num)) return Math.max(13, Math.min(70, Math.round(num)));
+
+  const match = text.match(/(\d{2})/);
+  if (!match) return null;
+  return Math.max(13, Math.min(70, Number(match[1])));
+}
+
+function normalizeGender(value) {
+  const raw = String(value ?? '').trim().toLowerCase();
+  if (!raw) return 'unknown';
+  if (raw === 'f' || raw.includes('female') || raw.includes('\u5973')) return 'female';
+  if (raw === 'm' || raw.includes('male') || raw.includes('\u7537')) return 'male';
+  return 'unknown';
+}
+
+function normalizeToken(value) {
+  const text = String(value ?? '').trim();
+  return text || null;
+}
+
+function normalizeSampleRow(row = {}) {
+  const normalized = {
+    age: null,
+    gender: 'unknown',
+    city: null,
+    occupation: null,
+    pain_point: null,
+    aspiration: null,
+  };
+
+  for (const [rawKey, rawValue] of Object.entries(row)) {
+    const key = CSV_FIELD_ALIASES[String(rawKey ?? '').trim().toLowerCase()] ?? null;
+    if (!key) continue;
+
+    if (key === 'age') normalized.age = parseAge(rawValue);
+    else if (key === 'gender') normalized.gender = normalizeGender(rawValue);
+    else normalized[key] = normalizeToken(rawValue);
+  }
+
+  return normalized;
+}
+
+function parseCsv(text, maxRows) {
+  const raw = String(text ?? '').trim();
+  if (!raw) return [];
+
+  const lines = raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (lines.length < 2) return [];
+
+  const headers = lines[0].split(',').map((item) => item.trim());
+  const rows = [];
+
+  for (const line of lines.slice(1)) {
+    if (rows.length >= maxRows) break;
+    const cols = line.split(',').map((item) => item.trim());
+    const row = {};
+    for (let i = 0; i < headers.length; i += 1) {
+      row[headers[i]] = cols[i] ?? '';
+    }
+    rows.push(normalizeSampleRow(row));
+  }
+
+  return rows;
+}
+
+function generateSyntheticSamples({ accountId, platform, count }) {
+  const benchmark = PLATFORM_BENCHMARKS[platform] ?? PLATFORM_BENCHMARKS.xhs;
+  const pools = benchmark.pools;
+
+  const samples = [];
+  for (let i = 0; i < count; i += 1) {
+    const ageNoise = deterministicRatio(accountId, `age:${i}`) * 14 - 7;
+    const age = Math.max(16, Math.min(55, Math.round(pools.age_peak + ageNoise)));
+    const isFemale = deterministicRatio(accountId, `gender:${i}`) < pools.female_ratio;
+
+    samples.push({
+      age,
+      gender: isFemale ? 'female' : 'male',
+      city: pools.cities[Math.floor(deterministicRatio(accountId, `city:${i}`) * pools.cities.length)],
+      occupation: pools.occupations[Math.floor(deterministicRatio(accountId, `job:${i}`) * pools.occupations.length)],
+      pain_point: pools.pain_points[Math.floor(deterministicRatio(accountId, `pain:${i}`) * pools.pain_points.length)],
+      aspiration: pools.aspirations[Math.floor(deterministicRatio(accountId, `asp:${i}`) * pools.aspirations.length)],
+    });
+  }
+
+  return samples;
+}
+
+function ageBucket(age) {
+  if (!Number.isFinite(age)) return null;
+  if (age <= 24) return '18-24';
+  if (age <= 34) return '25-34';
+  if (age <= 44) return '35-44';
+  return '45+';
+}
+
+function topItems(samples, key, limit = 5) {
+  const counter = new Map();
+  for (const sample of samples) {
+    const value = normalizeToken(sample?.[key]);
+    if (!value) continue;
+    counter.set(value, (counter.get(value) ?? 0) + 1);
+  }
+
+  return [...counter.entries()]
+    .sort((a, b) => {
+      if (b[1] !== a[1]) return b[1] - a[1];
+      return a[0].localeCompare(b[0], 'zh-Hans-CN');
+    })
+    .slice(0, limit)
+    .map((item) => item[0]);
+}
+
+function mergeDistinct(primary, fallback, limit = 5) {
+  const output = [];
+  const seen = new Set();
+
+  for (const value of [...primary, ...fallback]) {
+    const text = String(value ?? '').trim();
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    output.push(text);
+    if (output.length >= limit) break;
+  }
+
+  return output;
+}
+
+function inferAudience({ samples, benchmark }) {
+  const ageCounter = new Map();
+  let female = 0;
+  let male = 0;
+
+  for (const sample of samples) {
+    const bucket = ageBucket(sample.age);
+    if (bucket) ageCounter.set(bucket, (ageCounter.get(bucket) ?? 0) + 1);
+
+    if (sample.gender === 'female') female += 1;
+    else if (sample.gender === 'male') male += 1;
+  }
+
+  const topAgeBucket = [...ageCounter.entries()]
+    .sort((a, b) => {
+      if (b[1] !== a[1]) return b[1] - a[1];
+      return a[0].localeCompare(b[0]);
+    })[0]?.[0] ?? null;
+
+  const genderSkew = (() => {
+    const total = female + male;
+    if (total < 6) return benchmark.default_audience.gender_skew;
+    const femaleRatio = female / total;
+    const maleRatio = male / total;
+    if (femaleRatio >= 0.58) return '\u5973\u6027\u4e3b\u5bfc';
+    if (maleRatio >= 0.58) return '\u7537\u6027\u4e3b\u5bfc';
+    return '\u5747\u8861';
+  })();
+
+  return {
+    age_range: topAgeBucket ?? benchmark.default_audience.age_range,
+    gender_skew: genderSkew,
+    geo_focus: mergeDistinct(topItems(samples, 'city', 5), benchmark.default_audience.geo_focus, 5),
+    occupation_tags: mergeDistinct(topItems(samples, 'occupation', 5), benchmark.default_audience.occupation_tags, 5),
+    pain_points: mergeDistinct(topItems(samples, 'pain_point', 5), benchmark.default_audience.pain_points, 5),
+    aspirations: mergeDistinct(topItems(samples, 'aspiration', 5), benchmark.default_audience.aspirations, 5),
+  };
+}
+
+await startFixtureServer({
+  serverId: 'audience-research',
+  serverName: 'official-audience-research',
+  toolName: 'audience_research',
+  toolDescription: 'Build audience persona JSON from fixture fan snapshots plus optional uploaded CSV rows.',
+  inputSchema: {
+    account_id: z.string().min(1).describe('Target account identifier.'),
+    platform: z.enum(['xhs', 'douyin', 'wechat-mp']).optional()
+      .describe('Platform hint; inferred from account_id when omitted.'),
+    locale: z.string().optional().describe('Locale hint, default zh-CN.'),
+    follower_snapshot_csv: z.string().optional()
+      .describe('Optional CSV content. Headers supported: age,gender,city,occupation,pain_point,aspiration.'),
+    fan_samples: z.array(z.object({
+      age: z.union([z.number(), z.string()]).optional(),
+      gender: z.string().optional(),
+      city: z.string().optional(),
+      occupation: z.string().optional(),
+      pain_point: z.string().optional(),
+      aspiration: z.string().optional(),
+    })).optional().describe('Optional structured samples as an alternative to CSV upload.'),
+    sample_limit: z.number().int().min(20).max(400).optional()
+      .describe('Synthetic fan sample size for fixture estimation, default 90.'),
+  },
+  handler: ({
+    account_id,
+    platform,
+    locale = 'zh-CN',
+    follower_snapshot_csv,
+    fan_samples = [],
+    sample_limit = 90,
+  }) => {
+    const accountId = String(account_id ?? '').trim();
+    if (!accountId) throw new Error('account_id_required');
+
+    const normalizedPlatform = normalizePlatform(platform, accountId);
+    if (!Object.hasOwn(PLATFORM_BENCHMARKS, normalizedPlatform)) {
+      throw new Error(`unsupported_platform:${normalizedPlatform}`);
+    }
+
+    const benchmark = PLATFORM_BENCHMARKS[normalizedPlatform];
+    const normalizedLocale = String(locale ?? 'zh-CN').trim() || 'zh-CN';
+    const safeSampleLimit = clampInt(sample_limit, 20, 400, 90);
+
+    const csvSamples = parseCsv(follower_snapshot_csv, 300);
+    const directSamples = Array.isArray(fan_samples)
+      ? fan_samples.slice(0, 300).map((row) => normalizeSampleRow(row))
+      : [];
+
+    const syntheticSamples = generateSyntheticSamples({
+      accountId,
+      platform: normalizedPlatform,
+      count: safeSampleLimit,
+    });
+
+    const combinedSamples = [...syntheticSamples, ...directSamples, ...csvSamples];
+    const audience = inferAudience({
+      samples: combinedSamples,
+      benchmark,
+    });
+
+    return {
+      ...FIXTURE_META,
+      account_id: accountId,
+      platform: normalizedPlatform,
+      locale: normalizedLocale,
+      audience,
+      goal_schema_alignment: {
+        required_fields: ['age_range', 'gender_skew', 'geo_focus', 'occupation_tags', 'pain_points', 'aspirations'],
+        matched: true,
+      },
+      source_mix: {
+        synthetic_fan_samples: syntheticSamples.length,
+        direct_fan_samples: directSamples.length,
+        csv_fan_samples: csvSamples.length,
+        public_benchmark_platform: normalizedPlatform,
+      },
+      notes: {
+        mvp_mode: 'semi_automatic_supported',
+        csv_supported: true,
+        confidence: (directSamples.length + csvSamples.length) >= 20 ? 'medium' : 'medium_low',
+      },
+      generated_at: new Date().toISOString(),
+    };
+  },
+});

package/mcp-servers/official/audience-research/manifest.json

@@ -0,0 +1,18 @@
+{
+  "id": "audience-research",
+  "name": "Official Audience Research MCP",
+  "version": "0.1.0",
+  "runtime": "node",
+  "entrypoint": "index.js",
+  "tool_declarations": [
+    { "name": "audience_research", "classification": "cacheable" }
+  ],
+  "smoke_test": {
+    "tool": "audience_research",
+    "arguments": {
+      "account_id": "acct-xhs-demo-01",
+      "platform": "xhs",
+      "sample_limit": 60
+    }
+  }
+}