From b974407a8912c47be7339e8b6c56ad9aa74cca9c Mon Sep 17 00:00:00 2001 From: LordOfTheVillage Date: Tue, 17 Nov 2026 14:10:58 +0300 Subject: [PATCH] Signals --- package-lock.json | 12 +- package.json | 4 +- src/linked-api-server.ts | 7 + src/linked-api-tools.ts | 15 ++ src/tools/create-signal.ts | 271 +++++++++++++++++++++++++++ src/tools/delete-signal.ts | 41 ++++ src/tools/get-signal-events.ts | 89 +++++++++ src/tools/get-signal.ts | 41 ++++ src/tools/get-signals.ts | 59 ++++++ src/tools/pause-signal.ts | 41 ++++ src/tools/resume-signal.ts | 41 ++++ src/types/signal-events-page.type.ts | 8 + src/utils/page-signal-events.ts | 61 ++++++ src/utils/read-only-tool-names.ts | 3 + 14 files changed, 685 insertions(+), 8 deletions(-) create mode 100644 src/tools/create-signal.ts create mode 100644 src/tools/delete-signal.ts create mode 100644 src/tools/get-signal-events.ts create mode 100644 src/tools/get-signal.ts create mode 100644 src/tools/get-signals.ts create mode 100644 src/tools/pause-signal.ts create mode 100644 src/tools/resume-signal.ts create mode 100644 src/types/signal-events-page.type.ts create mode 100644 src/utils/page-signal-events.ts diff --git a/package-lock.json b/package-lock.json index f21e058..330fa1b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,15 +1,15 @@ { "name": "@linkedapi/mcp", - "version": "2.4.0", + "version": "2.5.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@linkedapi/mcp", - "version": "2.4.0", + "version": "2.5.0", "license": "MIT", "dependencies": { - "@linkedapi/node": "^2.4.0", + "@linkedapi/node": "^2.5.0", "@modelcontextprotocol/sdk": "^1.17.4", "zod": "^4.1.1" }, @@ -935,9 +935,9 @@ } }, "node_modules/@linkedapi/node": { - "version": "2.4.0", - "resolved": "https://registry.npmjs.org/@linkedapi/node/-/node-2.4.0.tgz", - "integrity": "sha512-29ZhdFlUjHe+tq5ZgLs19S/YiqKojxbnh6kkt/F0Sk9yOmBBJoQQq8H5jMqRbMmGcVk5Mh3dPnNhhvgqP+njIg==", + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@linkedapi/node/-/node-2.5.0.tgz", + "integrity": "sha512-MWzT2ibP73JmJ/lfo2c2XC25Te74jRWTQuHhMGZmkudv3lB3anryNKUPQZMqZ2LVjbepvcJ/imZmvS0yKoVeRg==", "license": "MIT" }, "node_modules/@modelcontextprotocol/sdk": { diff --git a/package.json b/package.json index e452edc..94dcc6b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@linkedapi/mcp", - "version": "2.4.0", + "version": "2.5.0", "description": "MCP server that lets AI assistants control LinkedIn accounts and retrieve real-time data.", "main": "dist/index.js", "bin": { @@ -30,7 +30,7 @@ "author": "Linked API", "license": "MIT", "dependencies": { - "@linkedapi/node": "^2.4.0", + "@linkedapi/node": "^2.5.0", "@modelcontextprotocol/sdk": "^1.17.4", "zod": "^4.1.1" }, diff --git a/src/linked-api-server.ts b/src/linked-api-server.ts index 0c7bf7e..6276dca 100644 --- a/src/linked-api-server.ts +++ b/src/linked-api-server.ts @@ -16,6 +16,13 @@ const NON_WORKFLOW_TOOL_NAMES = new Set([ 'get_workflow_result', 'get_api_usage', 'send_feedback', + 'create_signal', + 'get_signals', + 'get_signal', + 'pause_signal', + 'resume_signal', + 'delete_signal', + 'get_signal_events', ] as const); interface TExecuteWithTokensOptions extends TLinkedApiConfig { diff --git a/src/linked-api-tools.ts b/src/linked-api-tools.ts index 12394e8..859a1dd 100644 --- a/src/linked-api-tools.ts +++ b/src/linked-api-tools.ts @@ -23,6 +23,8 @@ import { CheckConnectionStatusTool } from './tools/check-connection-status.js'; import { CommentOnPostTool } from './tools/comment-on-post.js'; import { CreatePostTool } from './tools/create-post.js'; import { CreateRepostTool } from './tools/create-repost.js'; +import { CreateSignalTool } from './tools/create-signal.js'; +import { DeleteSignalTool } from './tools/delete-signal.js'; import { EndorsePersonSkillTool } from './tools/endorse-person-skill.js'; import { EndorsePersonSkillsTool } from './tools/endorse-person-skills.js'; import { ExecuteCustomWorkflowTool } from './tools/execute-custom-workflow.js'; @@ -35,6 +37,9 @@ import { GetChangelogTool } from './tools/get-changelog.js'; import { GetConversationTool } from './tools/get-conversation.js'; import { GetInboxTool } from './tools/get-inbox.js'; import { GetNetworkTool } from './tools/get-network.js'; +import { GetSignalEventsTool } from './tools/get-signal-events.js'; +import { GetSignalTool } from './tools/get-signal.js'; +import { GetSignalsTool } from './tools/get-signals.js'; import { GetWorkflowResultTool } from './tools/get-workflow-result.js'; import { IgnoreInvitationTool } from './tools/ignore-invitation.js'; import { ManageConversationTool } from './tools/manage-conversation.js'; @@ -63,6 +68,7 @@ import { NvSyncConversationTool } from './tools/nv-sync-conversation.js'; import { NvSyncInboxTool } from './tools/nv-sync-inbox.js'; import { NvUnsaveAccountTool } from './tools/nv-unsave-account.js'; import { NvUnsaveLeadTool } from './tools/nv-unsave-lead.js'; +import { PauseSignalTool } from './tools/pause-signal.js'; import { RcArchiveProjectTool } from './tools/rc-archive-project.js'; import { RcCreateProjectTool } from './tools/rc-create-project.js'; import { RcFetchPersonTool } from './tools/rc-fetch-person.js'; @@ -77,6 +83,7 @@ import { ReactToCommentTool } from './tools/react-to-comment.js'; import { ReactToPostTool } from './tools/react-to-post.js'; import { RemoveConnectionTool } from './tools/remove-connection.js'; import { ReplyToCommentTool } from './tools/reply-to-comment.js'; +import { ResumeSignalTool } from './tools/resume-signal.js'; import { RetrieveConnectionsTool } from './tools/retrieve-connections.js'; import { RetrieveFeedTool } from './tools/retrieve-feed.js'; import { RetrieveInvitationsTool } from './tools/retrieve-invitations.js'; @@ -192,6 +199,14 @@ export class LinkedApiTools { new RcArchiveProjectTool(), new RcSendMessageTool(), new RcSyncInboxTool(), + // Signal tools + new CreateSignalTool(), + new GetSignalsTool(), + new GetSignalTool(), + new PauseSignalTool(), + new ResumeSignalTool(), + new DeleteSignalTool(), + new GetSignalEventsTool(), // Other tools new ExecuteCustomWorkflowTool(), new GetWorkflowResultTool(), diff --git a/src/tools/create-signal.ts b/src/tools/create-signal.ts new file mode 100644 index 0000000..a678a0e --- /dev/null +++ b/src/tools/create-signal.ts @@ -0,0 +1,271 @@ +import LinkedApi, { + SIGNAL_TYPE, + TCreateSignalParams, + TMappedResponse, + TSignal, + TSignalPostSearchFilter, + TSignalType, +} from '@linkedapi/node'; +import { Tool } from '@modelcontextprotocol/sdk/types.js'; +import { z } from 'zod'; + +import { LinkedApiTool } from '../utils/linked-api-tool.js'; + +interface TCreateSignalArgs { + type: TSignalType; + label?: string; + personUrl?: string; + companyUrl?: string; + postUrl?: string; + myPosts?: true; + term?: Array; + filter?: TSignalPostSearchFilter; +} + +type TTargetField = Exclude; + +const TARGET_FIELDS: ReadonlyArray = [ + 'personUrl', + 'companyUrl', + 'postUrl', + 'myPosts', + 'term', + 'filter', +]; + +const TARGET_FIELDS_BY_TYPE = { + [SIGNAL_TYPE.personPosts]: ['personUrl'], + [SIGNAL_TYPE.companyPosts]: ['companyUrl'], + [SIGNAL_TYPE.postSearch]: ['term', 'filter'], + [SIGNAL_TYPE.postEngagement]: ['postUrl', 'myPosts'], + [SIGNAL_TYPE.network]: [], + [SIGNAL_TYPE.profileViewers]: [], +} as const satisfies Record>; + +const ACTOR_FILTER_ENTRY_SCHEMA = z.union([ + z.string().min(1), + z.object({ + name: z.string().min(1), + id: z.string().min(1).optional(), + }), +]); + +const ACTOR_FILTER_ENTRY_JSON_SCHEMA = { + anyOf: [ + { + type: 'string', + minLength: 1, + description: 'Name of the person or company, shorthand for { name }.', + }, + { + type: 'object', + properties: { + name: { + type: 'string', + minLength: 1, + description: 'Required. Name of the person or company.', + }, + id: { + type: 'string', + minLength: 1, + description: + 'Optional. URN or LinkedIn URL that pins the filter to exactly that person or company.', + }, + }, + required: ['name'], + }, + ], +}; + +export class CreateSignalTool extends LinkedApiTool { + public readonly name = 'create_signal'; + // One flat object rather than a union per type: ChatGPT wraps the arguments of a tool whose schema + // has a root anyOf/oneOf in { value }. Which fields go with which type is checked here instead. + protected readonly schema = z + .object({ + type: z.enum(Object.values(SIGNAL_TYPE)), + label: z.string().min(1).max(64).optional(), + personUrl: z.string().min(1).optional(), + companyUrl: z.string().min(1).optional(), + postUrl: z.string().min(1).optional(), + myPosts: z.literal(true).optional(), + term: z.array(z.string().min(1).max(50)).min(1).max(3).optional(), + filter: z + .object({ + contentType: z + .enum(['videos', 'images', 'jobPosts', 'liveVideos', 'documents']) + .optional(), + postedBy: z + .array(z.enum(['me', 'firstConnections', 'peopleYouFollow'])) + .min(1) + .optional(), + mentioningMembers: z.array(ACTOR_FILTER_ENTRY_SCHEMA).min(1).optional(), + mentioningCompanies: z.array(ACTOR_FILTER_ENTRY_SCHEMA).min(1).optional(), + authorCompanies: z.array(ACTOR_FILTER_ENTRY_SCHEMA).min(1).optional(), + authorIndustries: z.array(z.string().min(1)).min(1).optional(), + }) + .optional(), + }) + .superRefine((args, context) => { + const allowedFields: ReadonlyArray = TARGET_FIELDS_BY_TYPE[args.type]; + for (const field of TARGET_FIELDS) { + if (args[field] !== undefined && !allowedFields.includes(field)) { + context.addIssue({ + code: 'custom', + path: [field], + message: `Unexpected ${field} for ${args.type}`, + }); + } + } + + const missingTarget = findMissingTarget(args); + if (missingTarget) { + context.addIssue({ + code: 'custom', + message: missingTarget, + }); + } + }); + + public override async execute({ + linkedapi, + args, + }: { + linkedapi: LinkedApi; + args: TCreateSignalArgs; + }): Promise> { + return linkedapi.createSignal(args as TCreateSignalParams); + } + + public override getTool(): Tool { + return { + name: this.name, + description: + 'Create a signal: the account checks one thing on LinkedIn on a schedule and records every new item it finds as an event, which you read with get_signal_events. The first check records a silent baseline: what is already there is not reported, except that personPosts, companyPosts and postSearch signals report posts published since the signal was created. Creating a signal that already exists on the account (same type and target) returns that signal instead of a second one; a paused one stays paused. Pass only the target fields of the chosen type:\n' + + '- network: no target. Reports connectionAccepted, connectionAdded and connectionRequestReceived. Checked every hour; spends nothing from account limits.\n' + + '- profileViewers: no target. Reports profileViewed. Checked every 3 hours; spends nothing from account limits.\n' + + '- personPosts: personUrl. companyPosts: companyUrl. Reports postPublished. Checked once or twice a day. The first check opens the profile or company page once (1 of stPersonProfileViews or stCompanyPageViews, and the person may see the account among their profile viewers); later checks mostly run as LinkedIn searches and spend some stSearchQueries – usually a few a day for the whole account – plus occasional visits.\n' + + '- postSearch: term (1 to 3 phrases) and an optional filter. Reports postFound for new posts matching any phrase. Checked once or twice a day; each check spends 1 of stSearchQueries. By default an account has 300 searches a month and each postSearch signal spends 30 to 60 of them, so put the wordings of one topic into one signal rather than a signal per phrase.\n' + + '- postEngagement: postUrl, or myPosts: true for the posts the account publishes. Reports commentAdded and reactionAdded. Spends nothing from account limits, apart from occasional visits. A postUrl signal watches the post for 30 days, then stops.\n' + + 'Fails with signalLimitReached when the account already has the maximum number of active signals of this type: pause or delete one first.', + inputSchema: { + type: 'object', + properties: { + type: { + type: 'string', + enum: Object.values(SIGNAL_TYPE), + description: + 'What to watch: network, profileViewers, personPosts, companyPosts, postSearch or postEngagement.', + }, + label: { + type: 'string', + minLength: 1, + maxLength: 64, + description: + 'Optional. Your own identifier, up to 64 characters, such as a CRM record ID. It comes back with the signal and with every event it produces.', + }, + personUrl: { + type: 'string', + description: + "personPosts only, required there. LinkedIn profile URL of the person (e.g., 'https://www.linkedin.com/in/john-doe').", + }, + companyUrl: { + type: 'string', + description: + "companyPosts only, required there. LinkedIn company page URL (e.g., 'https://www.linkedin.com/company/example').", + }, + postUrl: { + type: 'string', + description: + 'postEngagement only. URL of the post whose new comments and reactions to report. Pass postUrl or myPosts, not both.', + }, + myPosts: { + type: 'boolean', + enum: [true], + description: + "postEngagement only. true to watch comments and reactions on the account's own posts. Pass postUrl or myPosts, not both.", + }, + term: { + type: 'array', + minItems: 1, + maxItems: 3, + items: { + type: 'string', + minLength: 1, + maxLength: 50, + }, + description: + 'postSearch only, required there. 1 to 3 phrases, each up to 50 characters and with no quotation marks inside; a single phrase is a one-item array. Each phrase is searched as an exact phrase, and a post containing any of them is reported.', + }, + filter: { + type: 'object', + description: + 'postSearch only, optional. Narrows the search; a post must match every field you set. The signal always looks for the newest posts, so there is no sort or date filter.', + properties: { + contentType: { + type: 'string', + enum: ['videos', 'images', 'jobPosts', 'liveVideos', 'documents'], + description: 'Kind of content the post must carry.', + }, + postedBy: { + type: 'array', + items: { + type: 'string', + enum: ['me', 'firstConnections', 'peopleYouFollow'], + }, + description: 'Author relationships to the account; matches any of them.', + }, + mentioningMembers: { + type: 'array', + items: ACTOR_FILTER_ENTRY_JSON_SCHEMA, + description: + 'People the post mentions; matches any of them. A name alone may match a namesake; an id pins the exact person.', + }, + mentioningCompanies: { + type: 'array', + items: ACTOR_FILTER_ENTRY_JSON_SCHEMA, + description: 'Companies the post mentions; matches any of them.', + }, + authorCompanies: { + type: 'array', + items: ACTOR_FILTER_ENTRY_JSON_SCHEMA, + description: 'Companies the author works at; matches any of them.', + }, + authorIndustries: { + type: 'array', + items: { type: 'string' }, + description: + 'Industries the author works in, by the names LinkedIn shows; matches any of them.', + }, + }, + }, + }, + required: ['type'], + } as Tool['inputSchema'], + }; + } +} + +function findMissingTarget({ + type, + personUrl, + companyUrl, + postUrl, + myPosts, + term, +}: TCreateSignalArgs): string | undefined { + switch (type) { + case SIGNAL_TYPE.personPosts: + return personUrl ? undefined : 'personPosts needs personUrl.'; + case SIGNAL_TYPE.companyPosts: + return companyUrl ? undefined : 'companyPosts needs companyUrl.'; + case SIGNAL_TYPE.postSearch: + return term ? undefined : 'postSearch needs term.'; + case SIGNAL_TYPE.postEngagement: + return Boolean(postUrl) !== Boolean(myPosts) + ? undefined + : 'postEngagement needs either postUrl or myPosts: true.'; + default: + return undefined; + } +} diff --git a/src/tools/delete-signal.ts b/src/tools/delete-signal.ts new file mode 100644 index 0000000..6509fef --- /dev/null +++ b/src/tools/delete-signal.ts @@ -0,0 +1,41 @@ +import LinkedApi, { TDeleteSignalResult, TMappedResponse, TSignalIdParams } from '@linkedapi/node'; +import { Tool } from '@modelcontextprotocol/sdk/types.js'; +import { z } from 'zod'; + +import { LinkedApiTool } from '../utils/linked-api-tool.js'; + +export class DeleteSignalTool extends LinkedApiTool { + public readonly name = 'delete_signal'; + protected readonly schema = z.object({ + signalId: z.string().min(1), + }); + + public override async execute({ + linkedapi, + args: { signalId }, + }: { + linkedapi: LinkedApi; + args: TSignalIdParams; + }): Promise> { + return linkedapi.deleteSignal({ signalId }); + } + + public override getTool(): Tool { + return { + name: this.name, + description: + 'Delete a signal; returns { deleted: true }. Its checks stop immediately. Events it already produced stay available in get_signal_events until their 90 days run out. To watch the target of a stopped signal again, delete it and create it again with create_signal. Fails with signalNotFound for an unknown id.', + inputSchema: { + type: 'object', + properties: { + signalId: { + type: 'string', + minLength: 1, + description: 'Signal id, as returned by create_signal or get_signals.', + }, + }, + required: ['signalId'], + }, + }; + } +} diff --git a/src/tools/get-signal-events.ts b/src/tools/get-signal-events.ts new file mode 100644 index 0000000..d0346ca --- /dev/null +++ b/src/tools/get-signal-events.ts @@ -0,0 +1,89 @@ +import LinkedApi, { + SIGNAL_EVENT_TYPE, + SIGNAL_TYPE, + TMappedResponse, + TSignalPollRequest, +} from '@linkedapi/node'; +import { Tool } from '@modelcontextprotocol/sdk/types.js'; +import { z } from 'zod'; + +import type { TSignalEventsPage } from '../types/signal-events-page.type.js'; +import { LinkedApiTool } from '../utils/linked-api-tool.js'; +import { pageSignalEvents } from '../utils/page-signal-events.js'; + +// Without since the poll returns up to 90 days of events, tens of megabytes on a busy account, and +// every next page would download the whole newer backlog again. +const DEFAULT_LOOKBACK_MS = 24 * 60 * 60 * 1000; + +export class GetSignalEventsTool extends LinkedApiTool { + public readonly name = 'get_signal_events'; + // Usually called with no arguments at all, which some clients send as an absent object. + protected readonly schema = z + .object({ + since: z.string().optional(), + signalId: z.string().min(1).optional(), + signalType: z.enum(Object.values(SIGNAL_TYPE)).optional(), + eventType: z.enum(Object.values(SIGNAL_EVENT_TYPE)).optional(), + }) + .default({}); + + public override async execute({ + linkedapi, + args: { since, signalId, signalType, eventType }, + }: { + linkedapi: LinkedApi; + args: TSignalPollRequest; + }): Promise> { + const pageSince = since ?? new Date(Date.now() - DEFAULT_LOOKBACK_MS).toISOString(); + const { data, errors } = await linkedapi.pollSignals({ + since: pageSince, + signalId, + signalType, + eventType, + }); + + return { + data: + data && + pageSignalEvents({ + since: pageSince, + events: data.events, + }), + errors, + }; + } + + public override getTool(): Tool { + return { + name: this.name, + description: + 'Read what signals detected (created with create_signal): new posts, comments, reactions, profile views and connection changes, one page at a time. Always pass since – the nextSince of your previous call – to read only what is new. Without since the tool reads the last 24 hours; pass an older since only when you need older events (they are kept 90 days). Returns { since, events, hasMore, nextSince }: since is the moment the page starts after; the page holds the earliest events recorded after it, listed newest first; nextSince is the newest detectedAt in the page. When hasMore is true, call again with since = nextSince for the next page – nothing is skipped or repeated. On a busy account narrow the read with signalId, signalType or eventType. Process each event once by its id. Every event carries signalId, signalType, label, type and detectedAt (when the check recorded it, not when it happened on LinkedIn), plus its subject: post (postPublished, postFound), postUrl and comment (commentAdded), postUrl and reaction (reactionAdded), viewer (profileViewed), or personUrn and personUrl (connectionAccepted, connectionAdded, connectionRequestReceived).', + inputSchema: { + type: 'object', + properties: { + since: { + type: 'string', + description: + "ISO 8601 timestamp: return events recorded after it (e.g., '2026-10-12T16:40:00.000Z'). Pass the nextSince of your previous call. Defaults to 24 hours ago.", + }, + signalId: { + type: 'string', + minLength: 1, + description: 'Optional. Only events of this signal.', + }, + signalType: { + type: 'string', + enum: Object.values(SIGNAL_TYPE), + description: 'Optional. Only events of signals of this type.', + }, + eventType: { + type: 'string', + enum: Object.values(SIGNAL_EVENT_TYPE), + description: 'Optional. Only events of this type.', + }, + }, + required: [], + }, + }; + } +} diff --git a/src/tools/get-signal.ts b/src/tools/get-signal.ts new file mode 100644 index 0000000..f099dc8 --- /dev/null +++ b/src/tools/get-signal.ts @@ -0,0 +1,41 @@ +import LinkedApi, { TMappedResponse, TSignal, TSignalIdParams } from '@linkedapi/node'; +import { Tool } from '@modelcontextprotocol/sdk/types.js'; +import { z } from 'zod'; + +import { LinkedApiTool } from '../utils/linked-api-tool.js'; + +export class GetSignalTool extends LinkedApiTool { + public readonly name = 'get_signal'; + protected readonly schema = z.object({ + signalId: z.string().min(1), + }); + + public override async execute({ + linkedapi, + args: { signalId }, + }: { + linkedapi: LinkedApi; + args: TSignalIdParams; + }): Promise> { + return linkedapi.getSignal({ signalId }); + } + + public override getTool(): Tool { + return { + name: this.name, + description: + 'Get one signal by its id, in the same shape as get_signals returns it: status, stoppedReason, baselineAt, lastCheckedAt, nextCheckAt, target fields and label. Fails with signalNotFound when the account has no signal with this id.', + inputSchema: { + type: 'object', + properties: { + signalId: { + type: 'string', + minLength: 1, + description: 'Signal id, as returned by create_signal or get_signals.', + }, + }, + required: ['signalId'], + }, + }; + } +} diff --git a/src/tools/get-signals.ts b/src/tools/get-signals.ts new file mode 100644 index 0000000..bd7d797 --- /dev/null +++ b/src/tools/get-signals.ts @@ -0,0 +1,59 @@ +import LinkedApi, { + SIGNAL_STATUS, + SIGNAL_TYPE, + TGetSignalsParams, + TGetSignalsResult, + TMappedResponse, +} from '@linkedapi/node'; +import { Tool } from '@modelcontextprotocol/sdk/types.js'; +import { z } from 'zod'; + +import { LinkedApiTool } from '../utils/linked-api-tool.js'; + +export class GetSignalsTool extends LinkedApiTool { + public readonly name = 'get_signals'; + // Usually called with no arguments at all, which some clients send as an absent object. + protected readonly schema = z + .object({ + type: z.enum(Object.values(SIGNAL_TYPE)).optional(), + status: z.enum(Object.values(SIGNAL_STATUS)).optional(), + }) + .default({}); + + public override async execute({ + linkedapi, + args: { type, status }, + }: { + linkedapi: LinkedApi; + args: TGetSignalsParams; + }): Promise> { + return linkedapi.getSignals({ + type, + status, + }); + } + + public override getTool(): Tool { + return { + name: this.name, + description: + "List the account's signals (created with create_signal). Each signal has id (pass it as signalId to the other signal tools), type, its target fields, label, status, stoppedReason, createdAt, baselineAt (when the first check completed, or null until then), lastCheckedAt and nextCheckAt (the planned next check, or null when the signal is not active; your workflows and working hours can move it). status is active (checked on schedule), paused, or stopped: Linked API stopped checking because the target can no longer be watched, and stoppedReason is targetNotFound or watchPeriodEnded. A stopped signal cannot be resumed; delete it and create it again.", + inputSchema: { + type: 'object', + properties: { + type: { + type: 'string', + enum: Object.values(SIGNAL_TYPE), + description: 'Optional. Return only signals of this type.', + }, + status: { + type: 'string', + enum: Object.values(SIGNAL_STATUS), + description: 'Optional. Return only signals with this status.', + }, + }, + required: [], + }, + }; + } +} diff --git a/src/tools/pause-signal.ts b/src/tools/pause-signal.ts new file mode 100644 index 0000000..2070d75 --- /dev/null +++ b/src/tools/pause-signal.ts @@ -0,0 +1,41 @@ +import LinkedApi, { TMappedResponse, TSignal, TSignalIdParams } from '@linkedapi/node'; +import { Tool } from '@modelcontextprotocol/sdk/types.js'; +import { z } from 'zod'; + +import { LinkedApiTool } from '../utils/linked-api-tool.js'; + +export class PauseSignalTool extends LinkedApiTool { + public readonly name = 'pause_signal'; + protected readonly schema = z.object({ + signalId: z.string().min(1), + }); + + public override async execute({ + linkedapi, + args: { signalId }, + }: { + linkedapi: LinkedApi; + args: TSignalIdParams; + }): Promise> { + return linkedapi.pauseSignal({ signalId }); + } + + public override getTool(): Tool { + return { + name: this.name, + description: + 'Pause a signal and return it. A paused signal is not checked and spends nothing; its events stay available in get_signal_events, and it does not count toward the active signal limit. Pausing an already paused signal changes nothing and succeeds. Resume it with resume_signal. Fails with signalNotFound for an unknown id and with signalStopped for a stopped signal.', + inputSchema: { + type: 'object', + properties: { + signalId: { + type: 'string', + minLength: 1, + description: 'Signal id, as returned by create_signal or get_signals.', + }, + }, + required: ['signalId'], + }, + }; + } +} diff --git a/src/tools/resume-signal.ts b/src/tools/resume-signal.ts new file mode 100644 index 0000000..1d110fd --- /dev/null +++ b/src/tools/resume-signal.ts @@ -0,0 +1,41 @@ +import LinkedApi, { TMappedResponse, TSignal, TSignalIdParams } from '@linkedapi/node'; +import { Tool } from '@modelcontextprotocol/sdk/types.js'; +import { z } from 'zod'; + +import { LinkedApiTool } from '../utils/linked-api-tool.js'; + +export class ResumeSignalTool extends LinkedApiTool { + public readonly name = 'resume_signal'; + protected readonly schema = z.object({ + signalId: z.string().min(1), + }); + + public override async execute({ + linkedapi, + args: { signalId }, + }: { + linkedapi: LinkedApi; + args: TSignalIdParams; + }): Promise> { + return linkedapi.resumeSignal({ signalId }); + } + + public override getTool(): Tool { + return { + name: this.name, + description: + 'Resume a paused signal and return it. Its first check reports what appeared while it was paused, as far as LinkedIn still shows it; it is not a new baseline. Resuming an active signal changes nothing and succeeds. Fails with signalLimitReached when the account already has the maximum number of active signals of this type (pause or delete one first), with signalStopped for a stopped signal or a postUrl signal whose 30-day watch period has ended, and with signalNotFound for an unknown id.', + inputSchema: { + type: 'object', + properties: { + signalId: { + type: 'string', + minLength: 1, + description: 'Signal id, as returned by create_signal or get_signals.', + }, + }, + required: ['signalId'], + }, + }; + } +} diff --git a/src/types/signal-events-page.type.ts b/src/types/signal-events-page.type.ts new file mode 100644 index 0000000..cdc12d2 --- /dev/null +++ b/src/types/signal-events-page.type.ts @@ -0,0 +1,8 @@ +import type { TSignalEvent } from '@linkedapi/node'; + +export interface TSignalEventsPage { + since: string; + events: Array; + hasMore: boolean; + nextSince: string; +} diff --git a/src/utils/page-signal-events.ts b/src/utils/page-signal-events.ts new file mode 100644 index 0000000..39daf78 --- /dev/null +++ b/src/utils/page-signal-events.ts @@ -0,0 +1,61 @@ +import type { TSignalEvent } from '@linkedapi/node'; + +import type { TSignalEventsPage } from '../types/signal-events-page.type.js'; + +// About 10k tokens of the pretty JSON the server returns, so one page fits a model's context. +const PAGE_CHARACTER_BUDGET = 40_000 as const; + +// The poll lists events newest first, its `since` is exclusive, and one check stamps all of its +// events with the same detectedAt. A page therefore takes whole checks, oldest first: calling again +// with the newest detectedAt of the page continues with no gap and no repeat. A check larger than the +// budget still goes out whole, since splitting it would lose the rest of it. +export function pageSignalEvents({ + since, + events, +}: { + since: string; + events: ReadonlyArray; +}): TSignalEventsPage { + const checks = groupChecksOldestFirst(events); + const page: Array = []; + let pageSize = 0; + let takenChecks = 0; + + for (const check of checks) { + const checkSize = check.reduce( + (size, event): number => size + JSON.stringify(event, null, 2).length, + 0, + ); + if (takenChecks > 0 && pageSize + checkSize > PAGE_CHARACTER_BUDGET) { + break; + } + + page.push(...check); + pageSize += checkSize; + takenChecks += 1; + } + + const newestFirst = page.reverse(); + + return { + since, + events: newestFirst, + hasMore: takenChecks < checks.length, + nextSince: newestFirst[0]?.detectedAt ?? since, + }; +} + +function groupChecksOldestFirst(events: ReadonlyArray): Array> { + const checks: Array> = []; + + for (const event of [...events].reverse()) { + const check = checks.at(-1); + if (check?.[0]?.detectedAt === event.detectedAt) { + check.push(event); + } else { + checks.push([event]); + } + } + + return checks; +} diff --git a/src/utils/read-only-tool-names.ts b/src/utils/read-only-tool-names.ts index 9639f3d..2e14418 100644 --- a/src/utils/read-only-tool-names.ts +++ b/src/utils/read-only-tool-names.ts @@ -19,6 +19,9 @@ export const READ_ONLY_TOOL_NAMES: ReadonlySet = new Set([ 'get_changelog', 'get_inbox', 'get_network', + 'get_signal', + 'get_signal_events', + 'get_signals', 'get_workflow_result', 'nv_fetch_company', 'nv_fetch_person',