Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
feat(mcp): add read tools for accounts and analytics
spacesdrive785f73ad40e0
diff --git a/backend/mcp/registry.ts b/backend/mcp/registry.tsindex 4c497c4..1c142ca 100644--- a/backend/mcp/registry.ts+++ b/backend/mcp/registry.ts@@ -1,10 +1,11 @@+import { ANALYTICS_TOOLS } from './tools/analyticsTools.ts';import { SCHEDULED_POST_TOOLS } from './tools/scheduledPostTools.ts';import { SETTINGS_TOOLS } from './tools/settingsTools.ts';import type { AnyTool } from './tool.ts';import type { ServerIdentity } from '../lib/mcp/protocol.ts';// every tool the MCP endpoint offers, in the order tools/list returns them; read-only callers see only the read tools-export const MCP_TOOLS: readonly AnyTool[] = [...SETTINGS_TOOLS, ...SCHEDULED_POST_TOOLS];+export const MCP_TOOLS: readonly AnyTool[] = [...ANALYTICS_TOOLS, ...SETTINGS_TOOLS, ...SCHEDULED_POST_TOOLS];export function mcpServerIdentity(version: string): ServerIdentity {return {diff --git a/backend/mcp/tools/analyticsTools.ts b/backend/mcp/tools/analyticsTools.tsnew file mode 100644index 0000000..0ea3dde--- /dev/null+++ b/backend/mcp/tools/analyticsTools.ts@@ -0,0 +1,191 @@+import { READ_ONLY, defineTool, noInput } from '../tool.ts';+import { idProperty, objectSchema, pageOf, pageProperties, parsePage, requiredId } from '../schemas.ts';+import { ValidationError } from '../../lib/errors.ts';+import type { Page } from '../schemas.ts';+import type { ToolAnnotations } from '../tool.ts';+import type { SafeAccount } from '../../../shared/types/domain.ts';+import type { InstagramMedia } from '../../../shared/types/instagram.ts';+import type { YouTubeVideo, YouTubeVideoSummary } from '../../../shared/types/youtube.ts';++// titles, captions and bios are written by people on the platforms, so the client is told the result holds them+const READ_PLATFORM_TEXT: ToolAnnotations = { ...READ_ONLY, openWorldHint: true };++// long captions are cut so a page of posts stays small; the permalink leads to the full text+const MAX_CAPTION_CHARS = 300;++const VIDEO_SORTS = ['recent', 'views'] as const;+type VideoSort = typeof VIDEO_SORTS[number];++function shortText(text: string | undefined): string {+ if (!text) return '';+ return text.length > MAX_CAPTION_CHARS ? `${text.slice(0, MAX_CAPTION_CHARS)}...` : text;+}++// the fields a person knows an account by; tokens are already gone from SafeAccount, and thumbnails add nothing+function accountSummary(account: SafeAccount) {+ return account.platform === 'instagram'+ ? {+ id: account.id, platform: account.platform, name: account.title ?? account.username ?? '', username: account.username ?? null,+ followers: account.followersCount ?? null, posts: account.mediaCount ?? null, lastUpdated: account.lastUpdated ?? null,+ }+ : {+ id: account.id, platform: account.platform, name: account.title ?? '', handle: account.customUrl ?? null,+ subscribers: account.hiddenSubscriberCount ? null : account.subscriberCount ?? null, views: account.viewCount ?? null,+ videos: account.videoCount ?? null, lastUpdated: account.lastUpdated ?? null,+ };+}++function videoBrief(video: YouTubeVideoSummary | null) {+ if (!video) return null;+ return { videoId: video.videoId, title: video.title, views: video.viewCount, likes: video.likeCount, comments: video.commentCount, publishedAt: video.publishedAt };+}++function videoRow(video: YouTubeVideo) {+ return {+ videoId: video.videoId, title: video.title, publishedAt: video.publishedAt, duration: video.duration,+ views: video.viewCount, likes: video.likeCount, comments: video.commentCount, privacy: video.privacyStatus,+ };+}++function mediaRow(media: InstagramMedia | null) {+ if (!media) return null;+ return {+ id: media.id, type: media.contentType, caption: shortText(media.caption), postedAt: media.timestamp,+ likes: media.likeCount, comments: media.commentsCount, views: media.viewCount, permalink: media.permalink,+ };+}++const accountIdInput = objectSchema({ accountId: idProperty('account') }, ['accountId']);++export const listAccounts = defineTool<Record<string, never>>({+ name: 'list_accounts',+ title: 'List connected accounts',+ description: 'Lists the YouTube channels and Instagram accounts in Twiligent with their headline figures. Use the ids with the other tools.',+ inputSchema: noInput(),+ annotations: READ_PLATFORM_TEXT,+ permission: 'read',+ parse: () => ({}),+ async run(_input, { services, principal }) {+ const accounts = await services.accounts.list(principal.userId);+ return { accounts: accounts.map(accountSummary) };+ },+});++export const getYouTubeChannelAnalytics = defineTool<{ accountId: string }>({+ name: 'get_youtube_channel_analytics',+ title: 'Get YouTube channel analytics',+ description: 'Gets a YouTube channel\'s figures from its public data: subscribers, views, upload totals and averages, engagement, growth estimates, and its best and most recent videos.',+ inputSchema: accountIdInput,+ annotations: READ_PLATFORM_TEXT,+ permission: 'read',+ parse: args => ({ accountId: requiredId(args, 'accountId', 'account') }),+ async run({ accountId }, { services, principal }) {+ const { channel, analytics, videoCount } = await services.youtubeAnalytics.channelAnalytics(principal.userId, accountId);+ return {+ channel: {+ ...accountSummary(channel), ageYears: channel.channelAgeYears, avgViewsPerDay: channel.avgViewsPerDay,+ avgSubscribersPerDay: channel.avgSubGainPerDay, estimatedMonthlyViews: channel.estimatedMonthlyViews,+ estimatedMonthlySubscribers: channel.estimatedMonthlySubGain,+ },+ uploads: {+ analysedVideos: videoCount, totalViews: analytics.totalViews, avgViews: analytics.avgViews, medianViews: analytics.medianViews,+ avgLikes: analytics.avgLikes, avgComments: analytics.avgComments, engagementRate: analytics.overallEngagementRate,+ avgDuration: analytics.avgDurationFormatted, estimatedWatchTimeHours: analytics.estimatedTotalWatchTimeHours,+ },+ videos: {+ bestByViews: videoBrief(analytics.bestByViews), bestByEngagement: videoBrief(analytics.bestByEngagement),+ worstByViews: videoBrief(analytics.worstByViews), mostRecent: videoBrief(analytics.mostRecent),+ },+ };+ },+});++export const listYouTubeVideos = defineTool<{ accountId: string; sort: VideoSort; page: Page }>({+ name: 'list_youtube_videos',+ title: 'List a channel\'s YouTube videos',+ description: 'Lists a YouTube channel\'s uploads with views, likes and comments, newest first or most viewed first.',+ inputSchema: objectSchema({+ accountId: idProperty('account'),+ sort: { type: 'string', enum: [...VIDEO_SORTS], description: 'recent (default) or views' },+ ...pageProperties,+ }, ['accountId']),+ annotations: READ_PLATFORM_TEXT,+ permission: 'read',+ parse(args) {+ const sort = args.sort ?? 'recent';+ if (!VIDEO_SORTS.includes(sort as VideoSort)) throw new ValidationError(`sort must be one of ${VIDEO_SORTS.join(', ')}`);+ return { accountId: requiredId(args, 'accountId', 'account'), sort: sort as VideoSort, page: parsePage(args) };+ },+ async run({ accountId, sort, page }, { services, principal }) {+ const { videos, fetchedAt } = await services.youtubeAnalytics.channelVideos(principal.userId, accountId);+ const ordered = [...videos].sort(sort === 'views'+ ? (a, b) => b.viewCount - a.viewCount+ : (a, b) => b.publishedAt.localeCompare(a.publishedAt));+ const { items, nextCursor, total } = pageOf(ordered, page);+ return { videos: items.map(videoRow), nextCursor, total, fetchedAt };+ },+});++export const compareYouTubeChannels = defineTool<Record<string, never>>({+ name: 'compare_youtube_channels',+ title: 'Compare YouTube channels',+ description: 'Compares all connected YouTube channels: combined totals and the leading channel by subscribers, views and videos.',+ inputSchema: noInput(),+ annotations: READ_PLATFORM_TEXT,+ permission: 'read',+ parse: () => ({}),+ async run(_input, { services, principal }) {+ const comparison = await services.youtubeAnalytics.comparison(principal.userId);+ if (!comparison) return { channels: 0, message: 'No YouTube channels are connected yet.' };+ const lead = (account: SafeAccount | null) => (account ? { id: account.id, name: account.title ?? '' } : null);+ return {+ channels: comparison.accountCount,+ totals: comparison.totals,+ leaders: { subscribers: lead(comparison.bestBySubscribers), views: lead(comparison.bestByViews), videos: lead(comparison.bestByVideos) },+ };+ },+});++export const getInstagramAccountAnalytics = defineTool<{ accountId: string }>({+ name: 'get_instagram_account_analytics',+ title: 'Get Instagram account analytics',+ description: 'Gets an Instagram account\'s followers, post totals and averages, engagement rate, results per content type, and its best posts.',+ inputSchema: accountIdInput,+ annotations: READ_PLATFORM_TEXT,+ permission: 'read',+ parse: args => ({ accountId: requiredId(args, 'accountId', 'account') }),+ async run({ accountId }, { services, principal }) {+ const { profile, analytics, mediaCount } = await services.instagramAnalytics.analytics(principal.userId, accountId);+ return {+ account: { id: accountId, username: profile.username, name: profile.name, followers: profile.followersCount, following: profile.followsCount, posts: mediaCount },+ posts: {+ analysedPosts: analytics.fetchedPosts, avgLikes: analytics.avgLikes, avgComments: analytics.avgComments, avgViews: analytics.avgViews,+ medianLikes: analytics.medianLikes, engagementRate: analytics.engagementRate, totalViews: analytics.totalViews,+ },+ byContentType: analytics.contentTypeStats,+ postFrequency: analytics.postFrequency,+ best: { byLikes: mediaRow(analytics.bestByLikes), byComments: mediaRow(analytics.bestByComments) },+ worstByLikes: mediaRow(analytics.worstByLikes),+ };+ },+});++export const listInstagramMedia = defineTool<{ accountId: string; page: Page }>({+ name: 'list_instagram_media',+ title: 'List Instagram posts',+ description: 'Lists an Instagram account\'s posts, newest first, with likes, comments, views and a link to each.',+ inputSchema: objectSchema({ accountId: idProperty('account'), ...pageProperties }, ['accountId']),+ annotations: READ_PLATFORM_TEXT,+ permission: 'read',+ parse: args => ({ accountId: requiredId(args, 'accountId', 'account'), page: parsePage(args) }),+ async run({ accountId, page }, { services, principal }) {+ const { media, fetchedAt } = await services.instagramAnalytics.media(principal.userId, accountId);+ const ordered = [...media].sort((a, b) => b.timestamp.localeCompare(a.timestamp));+ const { items, nextCursor, total } = pageOf(ordered, page);+ return { posts: items.map(mediaRow), nextCursor, total, fetchedAt };+ },+});++export const ANALYTICS_TOOLS = [+ listAccounts, getYouTubeChannelAnalytics, listYouTubeVideos, compareYouTubeChannels, getInstagramAccountAnalytics, listInstagramMedia,+];diff --git a/backend/tests/mcp/analyticsTools.test.ts b/backend/tests/mcp/analyticsTools.test.tsnew file mode 100644index 0000000..627e12d--- /dev/null+++ b/backend/tests/mcp/analyticsTools.test.ts@@ -0,0 +1,114 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import {+ ANALYTICS_TOOLS, compareYouTubeChannels, getInstagramAccountAnalytics, listAccounts, listInstagramMedia, listYouTubeVideos,+} from '../../mcp/tools/analyticsTools.ts';+import { NotFoundError, ValidationError } from '../../lib/errors.ts';+import type { Services } from '../../container.ts';+import type { ToolContext } from '../../mcp/tool.ts';+import type { AccountService } from '../../services/accountService.ts';+import type { InstagramAnalyticsService, InstagramAccountAnalytics } from '../../services/instagramAnalyticsService.ts';+import type { YouTubeAnalyticsService } from '../../services/youtubeAnalyticsService.ts';+import type { Account } from '../../../shared/types/domain.ts';+import type { InstagramMedia } from '../../../shared/types/instagram.ts';+import type { YouTubeVideo } from '../../../shared/types/youtube.ts';++const OWNER = 'user-1';++function video(videoId: string, publishedAt: string, viewCount: number): YouTubeVideo {+ return { videoId, title: `Video ${videoId}`, publishedAt, viewCount, likeCount: 1, commentCount: 0, duration: 'PT1M', privacyStatus: 'public' } as YouTubeVideo;+}++function media(id: string, timestamp: string, caption = 'Short caption'): InstagramMedia {+ return {+ id, caption, contentType: 'reel', mediaType: 'VIDEO', mediaUrl: 'https://cdn.example/m.mp4', thumbnailUrl: '', permalink: `https://instagram.com/p/${id}`,+ timestamp, likeCount: 3, commentsCount: 1, viewCount: 10,+ } as InstagramMedia;+}++const ACCOUNTS: Account[] = [+ { id: 'yt-1', platform: 'youtube', title: 'Cooking', customUrl: '@cooking', subscriberCount: 1200, viewCount: 50_000, videoCount: 40 },+ { id: 'ig-1', platform: 'instagram', title: 'Bakery', username: 'bakery', followersCount: 900, mediaCount: 120, accessToken: 'secret-ig-token' },+];++function context(userId = OWNER): ToolContext {+ const owns = (id: string) => userId === OWNER && ACCOUNTS.some(account => account.id === id);+ const accounts: Pick<AccountService, 'list'> = {+ // the real service strips the token; the fake leaves it in so the tool's own summary is what is tested+ list: async id => (id === OWNER ? ACCOUNTS : []),+ };+ const youtubeAnalytics: Pick<YouTubeAnalyticsService, 'channelVideos' | 'comparison'> = {+ async channelVideos(_user, accountId) {+ if (!owns(accountId)) throw new NotFoundError('YouTube channel not found');+ return { videos: [video('old', '2025-01-01T00:00:00Z', 900), video('new', '2026-10-01T00:00:00Z', 50), video('mid', '2026-01-01T00:00:00Z', 300)], fetchedAt: '2026-11-05T00:00:00Z' };+ },+ comparison: async id => (id === OWNER+ ? { rankings: {} as never, totals: { subscribers: 1200, views: 50_000, videos: 40 }, accountCount: 1, bestBySubscribers: ACCOUNTS[0], bestByViews: ACCOUNTS[0], bestByVideos: ACCOUNTS[0] }+ : null),+ };+ const instagramAnalytics: Pick<InstagramAnalyticsService, 'media' | 'analytics'> = {+ async media(_user, accountId) {+ if (!owns(accountId)) throw new NotFoundError('Instagram account not found');+ return { media: [media('a', '2026-10-01T00:00:00Z', 'x'.repeat(1000)), media('b', '2026-11-01T00:00:00Z')], fetchedAt: '2026-11-05T00:00:00Z' };+ },+ async analytics(_user, accountId) {+ if (!owns(accountId)) throw new NotFoundError('Instagram account not found');+ return {+ profile: { username: 'bakery', name: 'Bakery', followersCount: 900, followsCount: 10, mediaCount: 120 },+ account: ACCOUNTS[1],+ analytics: { fetchedPosts: 2, avgLikes: 3, bestByLikes: media('b', '2026-11-01T00:00:00Z'), bestByComments: null, worstByLikes: null, contentTypeStats: {}, postFrequency: {} },+ mediaCount: 120,+ } as unknown as InstagramAccountAnalytics;+ },+ };+ return {+ services: { accounts, youtubeAnalytics, instagramAnalytics } as unknown as Services,+ principal: { userId, permission: 'read', via: 'token:t1' },+ };+}++test('every analytics tool only reads', () => {+ for (const tool of ANALYTICS_TOOLS) {+ assert.equal(tool.permission, 'read', tool.name);+ assert.equal(tool.annotations.readOnlyHint, true, tool.name);+ }+});++test('listing accounts gives headline figures and never an access token', async () => {+ const result = await listAccounts.run({}, context()) as { accounts: { id: string; platform: string }[] };+ assert.deepEqual(result.accounts.map(account => account.id), ['yt-1', 'ig-1']);+ assert.ok(!JSON.stringify(result).includes('secret-ig-token'));+ const other = await listAccounts.run({}, context('user-2')) as { accounts: unknown[] };+ assert.deepEqual(other.accounts, []);+});++test('videos are sorted newest or most viewed first and paged', async () => {+ const recent = await listYouTubeVideos.run(listYouTubeVideos.parse({ accountId: 'yt-1', limit: 2 }), context()) as { videos: { videoId: string }[]; nextCursor: string; total: number };+ assert.deepEqual(recent.videos.map(item => item.videoId), ['new', 'mid']);+ assert.equal(recent.nextCursor, '2');+ assert.equal(recent.total, 3);+ const popular = await listYouTubeVideos.run(listYouTubeVideos.parse({ accountId: 'yt-1', sort: 'views' }), context()) as { videos: { videoId: string }[] };+ assert.deepEqual(popular.videos.map(item => item.videoId), ['old', 'mid', 'new']);+ assert.throws(() => listYouTubeVideos.parse({ accountId: 'yt-1', sort: 'likes' }), ValidationError);+ assert.throws(() => listYouTubeVideos.parse({}), ValidationError);+});++test('another person\'s channel or account is not found', async () => {+ await assert.rejects(listYouTubeVideos.run(listYouTubeVideos.parse({ accountId: 'yt-1' }), context('user-2')), NotFoundError);+ await assert.rejects(getInstagramAccountAnalytics.run({ accountId: 'ig-1' }, context('user-2')), NotFoundError);+});++test('Instagram posts come newest first with long captions cut short', async () => {+ const result = await listInstagramMedia.run(listInstagramMedia.parse({ accountId: 'ig-1' }), context()) as { posts: { id: string; caption: string }[] };+ assert.deepEqual(result.posts.map(item => item.id), ['b', 'a']);+ assert.equal(result.posts[1].caption.length, 303);+ assert.ok(result.posts[1].caption.endsWith('...'));+});++test('comparing channels names the leaders, and says so when there are none', async () => {+ const result = await compareYouTubeChannels.run({}, context()) as { channels: number; leaders: { views: { id: string } } };+ assert.equal(result.channels, 1);+ assert.equal(result.leaders.views.id, 'yt-1');+ const none = await compareYouTubeChannels.run({}, context('user-2')) as { channels: number; message: string };+ assert.equal(none.channels, 0);+});