Unlinked AGENTS.md

AGENTS.md

Project Purpose

This repository is Unlinked, a TypeScript MCP server that connects a user's LinkedIn professional profile and experience data to AI assistants such as Claude Desktop, GitHub Copilot, and other Model Context Protocol clients.

Unlinked exists to let a member bring their own professional context into an assistant without making the assistant scrape LinkedIn, infer profile details, or rely on stale manually copied text. The LinkedIn API surface used here is read-only.

Core Requirements

• Build the server with the official TypeScript MCP SDK, @modelcontextprotocol/sdk.
• Run the MCP server from the CLI over stdio with StdioServerTransport.
• Keep the project usable by desktop MCP clients, especially Claude Desktop and GitHub Copilot.
• Connect to LinkedIn's Member Data Portability (Member) API product.
• Fetch LinkedIn member profile and professional-history data for the authenticated member.
• Treat the LinkedIn access token as a startup secret. Read it from the LINKEDIN_TOKEN environment variable. Use it only to send Authorization: Bearer <access_token> to LinkedIn. Do not persist it, log it, echo it into MCP responses, or put it in package scripts.
• Make clear in user-facing docs and errors that the Member Data Portability product is currently available only to LinkedIn members in the European Economic Area and Switzerland.
• Preserve the API's read-only nature. Do not add tools that mutate LinkedIn data.

LinkedIn API Notes

The main documentation is LinkedIn's Microsoft Learn page for Member Data Portability (Member).

Before implementing or changing LinkedIn API behavior, also read the local skill at .agents/skills/linkedin-member-data-portability/SKILL.md.

Important behavior from the docs:

• Access requires a LinkedIn Developer application provisioned with the Member Data Portability API (Member) product.
• The OAuth Token Generator flow is currently available only to members located in the EEA and Switzerland.
• The token generator documentation currently instructs members to request the r_dma_portability_self_serve scope. The Snapshot and Changelog API pages also describe DMA portability permissions such as r_dma_portability_member and r_dma_portability_3rd_party. Follow the current docs and surface authorization failures clearly.
• The LinkedIn API version is configured with LINKEDIN_API_VERSION and defaults to 202312 when unset. The value must be in YYYYMM format (e.g. 202312, 202501). Do not use v2 or any other non-date format.
• Snapshot data is fetched with GET https://api.linkedin.com/rest/memberSnapshotData?q=criteria and optional domain query parameter.
• Professional profile domains to prioritize include PROFILE, POSITIONS, EDUCATION, SKILLS, CERTIFICATIONS, PROJECTS, ORGANIZATIONS, LANGUAGES, HONORS, COURSES, PUBLICATIONS, PATENTS, VOLUNTEERING_EXPERIENCES, and RECOMMENDATIONS.
• Snapshot responses may be paginated. Follow paging.links until no next page remains, and account for the docs' warning that paging.total may not fully reflect all pages.
• Changelog events are fetched with GET https://api.linkedin.com/rest/memberChangeLogs?q=memberAndApplication. They cover events generated after member consent and are currently limited to the past 28 days.
• Changelog polling should support startTime, use the latest returned processedAt as the next cursor, default to modest page sizes, and respect the documented upper count limit of 50.
• LinkedIn errors use standard HTTP status codes and JSON bodies with message, serviceErrorCode, and status. Return helpful MCP errors without leaking tokens.