{
  "markdown": "# @limelink/mcp\n\n[![npm version](https://img.shields.io/npm/v/%40limelink%2Fmcp.svg)](https://www.npmjs.com/package/@limelink/mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[한국어](./README.ko.md) · [Documentation](https://github.com/hellovelop/limelink-mcp-server/blob/main/docs/README.md) · [Capability reference](https://github.com/hellovelop/limelink-mcp-server/blob/main/docs/capabilities/README.md)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [LimeLink](https://limelink.org) dynamic link management. Create, look up, and manage dynamic links directly from Claude Code, Claude Desktop, or any MCP-compatible client.\n\n> **No API key required to get started!** Documentation and SDK setup guides work without any configuration. Just connect and start exploring LimeLink features with your AI assistant.\n\n## Features\n\n- **Documentation Resources** — Access LimeLink docs (15 pages + index) directly from your AI assistant — **no API key needed**\n- **5 Tools** — Discover profiles and Projects, create dynamic links, and look up links (API tools require a configured profile)\n- **In-memory Caching** — 1-hour TTL cache for documentation fetches\n\n### Runtime\n\n- Node.js 18 or later\n- stdio transport only; Remote MCP/HTTP transport is not supported\n- npm package: `@limelink/mcp`; global executable: `limelink-mcp`\n- stdout is reserved for the MCP protocol; diagnostics and wrapper logs must use stderr\n\nSee [installation and configuration](https://github.com/hellovelop/limelink-mcp-server/blob/main/docs/operations/CONFIGURATION.md) and [network behavior](https://github.com/hellovelop/limelink-mcp-server/blob/main/docs/operations/NETWORK_BEHAVIOR.md) for the complete operational contract.\n\n### What works without an API key?\n\n| Feature | Category | API Key | Description |\n|---------|----------|:-------:|-------------|\n| `limelink://docs/index` | Resource | Not needed | Full documentation index |\n| `limelink://docs/{slug}` | Resource | Not needed | 15 individual documentation pages |\n| `list-profiles` | Tool | Not needed | List locally configured profile aliases without contacting the API |\n| `list-projects` | Tool | **Required** | List Projects for a selected Organization profile |\n| `list-custom-domains` | Tool | **Required** | List Custom Domains for a selected Project |\n| `create-link` | Tool | **Required** | Create V2 Core Links via API |\n| `get-link-by-suffix` | Tool | **Required** | Look up links by suffix |\n| `get-link-by-url` | Tool | **Required** | Look up links by URL |\n\n## Quick Start\n\n### Without API Key (Documentation & Guides)\n\nNo API key needed. Connect and start exploring LimeLink documentation and setup guides immediately:\n\n```json\n{\n  \"mcpServers\": {\n    \"limelink\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@limelink/mcp\"]\n    }\n  }\n}\n```\n\nTry asking your AI assistant:\n- \"Read the LimeLink getting-started docs\"\n- \"How do I set up deep linking for iOS?\"\n- \"Show me the LimeLink SDK integration guide\"\n\n### With Organization Profiles (Full Features)\n\nCreate the version 1 profile file shown below and pass its absolute path:\n\n```json\n{\n  \"mcpServers\": {\n    \"limelink\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@limelink/mcp\"],\n      \"env\": {\n        \"LIMELINK_PROFILES_FILE\": \"/absolute/path/to/limelink-profiles.json\"\n      }\n    }\n  }\n}\n```\n\n### Usage with Global Install\n\n```bash\nnpm install -g @limelink/mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"limelink\": {\n      \"command\": \"limelink-mcp\",\n      \"env\": {\n        \"LIMELINK_PROFILES_FILE\": \"/absolute/path/to/limelink-profiles.json\"\n      }\n    }\n  }\n}\n```\n\n## Configuration\n\n### Claude Code\n\nThe easiest way to add the MCP server is using the `claude mcp add` command:\n\n```bash\n# Without API key (docs & guides only)\nclaude mcp add --scope user --transport stdio limelink -- npx -y @limelink/mcp\n\n# With API key (full features)\nclaude mcp add --scope user --transport stdio limelink \\\n  --env LIMELINK_PROFILES_FILE=/absolute/path/to/limelink-profiles.json \\\n  -- npx -y @limelink/mcp\n```\n\n**Scope options:**\n- `--scope user` — Available in all projects\n- `--scope project` — Saved to `.mcp.json` (shareable with team via Git)\n\n### Claude Desktop & other MCP clients\n\nAdd the JSON config to your client's config file:\n\n| Client | Config File |\n|--------|-------------|\n| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Claude Desktop (Windows) | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n\n### Profile file\n\n```json\n{\"version\":1,\"defaultProfile\":\"work\",\"profiles\":{\"work\":{\"apiKey\":\"your_api_key\",\"organizationLabel\":\"Work\",\"projects\":{\"marketing\":\"11111111-1111-4111-8111-111111111111\"}}}}\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `LIMELINK_PROFILES_FILE` | No | — | Path to a version 1 JSON file containing named Organization credential profiles. |\n\n`LIMELINK_API_KEY` and `LIMELINK_PROJECT_ID` are ignored. When no credential profile is configured, API-backed tools direct the agent to [Organizations](https://limelink.org/organizations) to issue an Organization API key and configure the profile file. Project-backed tools accept a Project UUID directly. A profile's optional `projects` map is a recommended convenience for repeatedly used Projects, not a prerequisite; add aliases after `list-projects` discovery if useful. Profiles initialize lazily through credential introspection on their first API-backed call. Profile-file changes, including alias additions, require an MCP server restart.\n\n> You can get your API key from the [LimeLink Dashboard](https://limelink.org/dashboard). Without an API key, documentation resources and SDK setup guides are fully available.\n\n## Tools\n\n### `list-profiles`\n\nLists configured aliases, Organization labels, default status, and current initialization status without contacting the API. Already initialized profiles include scopes. API key values remain secret and are never returned. Organization, Project, Custom Domain and credential identifiers and key prefixes are non-secret identifiers and may appear in API-backed tool responses when useful.\n\n### `list-projects`\n\nLists Projects in the Organization discovered from the selected profile's credential. Accepts optional `profile`; the credential requires `projects:read`.\n\n### `list-custom-domains`\n\nLists Custom Domains for required `project` (alias or UUID). Accepts optional `profile`; the credential requires `domains:read`.\n\n### `create-link`\n\nCreate a V2 Core Link with platform-specific deep linking, Custom Domain selection, social previews, and UTM tracking.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `dynamic_link_suffix` | string | No | Short URL path identifier (1–100); API-generated when omitted |\n| `dynamic_link_url` | string | Yes | Target URL (max 500) |\n| `dynamic_link_name` | string | Yes | Link name (max 100) |\n| `project` | string | Yes | Project alias in the selected profile or Project UUID |\n| `profile` | string | No | Profile alias; otherwise uses configured default or sole profile |\n| `custom_domain_id` | UUID string | No | Custom Domain for the Core Link |\n| `stats_flag` | boolean | No | Enable analytics tracking |\n| `apple_options` | object | No | iOS deep linking options |\n| `android_options` | object | No | Android deep linking options |\n| `additional_options` | object | No | Social preview + UTM options |\n\n**Example usage in Claude:**\n\n> \"Create a dynamic link for https://example.com/product/123 with suffix 'product-123' and enable analytics\"\n\n### `get-link-by-suffix`\n\nLook up a dynamic link by its suffix.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `suffix` | string | Yes | Dynamic link suffix |\n| `project` | string | Yes | Project alias in the selected profile or Project UUID |\n| `profile` | string | No | Profile alias; otherwise uses configured default or sole profile |\n\n### `get-link-by-url`\n\nResolve a Link through the V2 API using its full URL. The backend determines whether the URL belongs to a Free default namespace, Project hostname, or active Custom Domain. No Project selector or local suffix parsing is required.\n\nThe URL must be absolute HTTPS with exactly one `/{suffix}` path segment and no query, fragment, explicit port, or credentials.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `url` | string | Yes | Full LimeLink URL to resolve (max 2048 characters) |\n| `profile` | string | No | Profile alias; otherwise uses configured default or sole profile |\n\n## Resources\n\n### `limelink://docs/index`\n\nReturns the full LimeLink documentation index (`llms.txt`).\n\n### `limelink://docs/{slug}`\n\nReturns individual documentation pages. Available slugs:\n\n`introduction`, `getting-started`, `project`, `application`, `dynamic-link`, `create-link`, `link-detail`, `link-management`, `appearance`, `sdk-integration`, `ios-sdk`, `android-sdk`, `api-integration`, `advanced`, `llm-agent`\n\n**Example usage in Claude:**\n\n> \"Read the LimeLink API integration docs\"\n>\n> Claude will access `limelink://docs/api-integration`\n\n## Development\n\n### Prerequisites\n\n- Node.js >= 18\n- pnpm\n\n### Setup\n\n```bash\ngit clone https://github.com/hellovelop/limelink-mcp-server.git\ncd limelink-mcp-server\npnpm install\npnpm run build\n```\n\n### Run locally\n\n```bash\nLIMELINK_PROFILES_FILE=/absolute/path/to/limelink-profiles.json node dist/index.js\n```\n\n### Testing\n\n```bash\npnpm test          # Unit tests\npnpm test:e2e      # E2E tests (MCP stdio communication)\npnpm test:watch    # Unit tests in watch mode\npnpm test:coverage # Coverage report\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # Entry point\n├── lib/\n│   ├── config.ts         # Environment variable loading\n│   ├── cache.ts          # In-memory TTL cache\n│   ├── api-client.ts     # LimeLink API HTTP client\n│   └── doc-fetcher.ts    # Documentation fetcher with caching\n├── tools/\n│   ├── create-link.ts    # create-link tool\n│   ├── get-link-by-suffix.ts\n│   └── get-link-by-url.ts\n└── resources/\n    └── documentation.ts  # Documentation resources\n```\n\n## License\n\nMIT\n",
  "bytes": 10316,
  "sha": "5d495ecf21cb930f4453aecf2c533ba60441aadbf7630f2a5fa5a1f58094c432",
  "repo_slug": "hellovelop/limelink-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hellovelop_limelink_mcp_server_efa17965/readme"
}