Skip to content

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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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);
+});