@ulinkly/mcp-server 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +80 -52
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,12 +1,24 @@
1
- # @ulinkly/mcp-server
1
+ # ULink MCP Server
2
2
 
3
- Model Context Protocol (MCP) server for [ULink](https://ulink.ly) -- manage deep links, domains, and projects from AI coding tools like Claude Code and Cursor.
3
+ > Connect your ULink deep linking projects to Claude Code, Cursor, Windsurf, and other AI assistants.
4
4
 
5
- ## Quick Start
5
+ The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) standardizes how Large Language Models (LLMs) talk to external services like ULink. It connects AI assistants directly with your ULink account and allows them to perform tasks like managing projects, creating smart links, configuring domains, and more. See the [full list of tools](#tools).
6
6
 
7
- Add the following to your MCP client configuration:
7
+ ## Setup
8
8
 
9
- **Claude Code** (`~/.claude/claude_desktop_config.json`):
9
+ ### 1. Install the MCP server
10
+
11
+ Choose your MCP client and run the corresponding command:
12
+
13
+ **Claude Code:**
14
+
15
+ ```bash
16
+ claude mcp add ulink -- npx -y @ulinkly/mcp-server
17
+ ```
18
+
19
+ **Cursor:**
20
+
21
+ Open **Settings > MCP > Add new MCP server**, or add to `.cursor/mcp.json`:
10
22
 
11
23
  ```json
12
24
  {
@@ -19,7 +31,9 @@ Add the following to your MCP client configuration:
19
31
  }
20
32
  ```
21
33
 
22
- **Cursor** (`.cursor/mcp.json`):
34
+ **Windsurf:**
35
+
36
+ Open **Settings > MCP > Add new MCP server**, or add to `~/.windsurf/mcp.json`:
23
37
 
24
38
  ```json
25
39
  {
@@ -32,17 +46,27 @@ Add the following to your MCP client configuration:
32
46
  }
33
47
  ```
34
48
 
35
- On first use the server opens your browser for authentication. After you log in, the session persists and tokens refresh automatically.
49
+ If you don't see your MCP client listed above, check your client's MCP documentation and use the following server command:
50
+
51
+ ```
52
+ npx -y @ulinkly/mcp-server
53
+ ```
54
+
55
+ ### 2. Authenticate
36
56
 
37
- ## Authentication
57
+ Your MCP client will automatically open a browser window for authentication on first use. Log in with your ULink account and authorize the MCP server. The session persists and tokens refresh automatically.
38
58
 
39
- ### OAuth (default)
59
+ #### API Key (alternative)
40
60
 
41
- No configuration needed. The server launches a browser-based login flow using Supabase Auth with PKCE. Access tokens refresh automatically before they expire. If a refresh fails, the browser flow is re-triggered.
61
+ For CI environments or headless servers, set the `ULINK_API_KEY` environment variable to skip the browser flow:
42
62
 
43
- ### API Key
63
+ **Claude Code:**
44
64
 
45
- Set the `ULINK_API_KEY` environment variable to skip the browser flow entirely. This is useful for CI environments or headless servers.
65
+ ```bash
66
+ claude mcp add ulink -e ULINK_API_KEY=your-api-key -- npx -y @ulinkly/mcp-server
67
+ ```
68
+
69
+ **Manual config:**
46
70
 
47
71
  ```json
48
72
  {
@@ -51,7 +75,7 @@ Set the `ULINK_API_KEY` environment variable to skip the browser flow entirely.
51
75
  "command": "npx",
52
76
  "args": ["-y", "@ulinkly/mcp-server"],
53
77
  "env": {
54
- "ULINK_API_KEY": "your-api-key-here"
78
+ "ULINK_API_KEY": "your-api-key"
55
79
  }
56
80
  }
57
81
  }
@@ -60,69 +84,73 @@ Set the `ULINK_API_KEY` environment variable to skip the browser flow entirely.
60
84
 
61
85
  You can generate an API key from the ULink dashboard under **Project Settings > API Keys**, or by using the `create_api_key` tool.
62
86
 
87
+ ### 3. Start building
88
+
89
+ Once connected, your AI assistant can manage your ULink projects directly. Try asking it to:
90
+
91
+ - "List my ULink projects"
92
+ - "Create a new smart link for my app"
93
+ - "Show click analytics for my latest link"
94
+ - "Add a custom domain to my project"
95
+
63
96
  ## Tools
64
97
 
65
- The server exposes 21 tools organized into five categories.
98
+ The following ULink tools are available to the LLM, organized by category.
66
99
 
67
- ### Projects (5 tools)
100
+ #### Project Management
68
101
 
69
- | Tool | Description |
70
- |------|-------------|
71
- | `list_projects` | List all projects owned by or shared with the authenticated user |
72
- | `get_project` | Get detailed information about a specific project |
73
- | `create_project` | Create a new project with a name and default fallback URL |
74
- | `update_project` | Update the name or default URL of an existing project |
75
- | `configure_project` | Set platform-specific config (iOS bundle ID, Android package, deeplink schemas, SHA-256 fingerprints) |
102
+ - `list_projects`: Lists all ULink projects owned by or shared with the authenticated user.
103
+ - `get_project`: Gets detailed information about a specific project, including configuration and membership.
104
+ - `create_project`: Creates a new project with a name and default fallback URL.
105
+ - `update_project`: Updates the name or default URL of an existing project.
106
+ - `configure_project`: Sets platform-specific configuration (iOS bundle ID, Android package name, deeplink schemas, SHA-256 fingerprints).
76
107
 
77
- ### Links (6 tools)
108
+ #### Link Management
78
109
 
79
- | Tool | Description |
80
- |------|-------------|
81
- | `create_link` | Create a unified or dynamic smart link with platform-specific URLs and parameters |
82
- | `list_links` | List all links in a project with pagination |
83
- | `get_link` | Get detailed information about a specific link |
84
- | `update_link` | Update a link's URLs, parameters, or metadata |
85
- | `delete_link` | Permanently delete a link |
86
- | `get_link_analytics` | Get click analytics for a link (total clicks, platform/country/referrer breakdowns) |
110
+ - `create_link`: Creates a unified or dynamic smart link with platform-specific URLs, parameters, and metadata.
111
+ - `list_links`: Lists all links in a project with pagination.
112
+ - `get_link`: Gets detailed information about a specific link.
113
+ - `update_link`: Updates a link's URLs, parameters, or metadata.
114
+ - `delete_link`: Permanently deletes a link. This is irreversible.
115
+ - `get_link_analytics`: Gets click analytics for a link, including total clicks and breakdowns by platform, country, and referrer.
87
116
 
88
- ### Domains (4 tools)
117
+ #### Domain Management
89
118
 
90
- | Tool | Description |
91
- |------|-------------|
92
- | `list_domains` | List all domains (shared and custom) associated with a project |
93
- | `add_domain` | Add a custom domain to a project |
94
- | `verify_domain` | Trigger DNS verification for a custom domain |
95
- | `delete_domain` | Remove a custom domain from a project |
119
+ - `list_domains`: Lists all domains (shared and custom) associated with a project.
120
+ - `add_domain`: Adds a custom domain to a project. Requires DNS configuration and verification.
121
+ - `verify_domain`: Triggers DNS verification for a custom domain.
122
+ - `delete_domain`: Removes a custom domain from a project. Links using this domain will stop working.
96
123
 
97
- ### API Keys (3 tools)
124
+ #### API Keys
98
125
 
99
- | Tool | Description |
100
- |------|-------------|
101
- | `list_api_keys` | List all API keys for a project (metadata only, not the key value) |
102
- | `create_api_key` | Create a new API key (the full key is only shown once) |
103
- | `revoke_api_key` | Permanently revoke an API key |
126
+ - `list_api_keys`: Lists all API keys for a project (metadata only, not the key value).
127
+ - `create_api_key`: Creates a new API key. The full key is only returned once — store it securely.
128
+ - `revoke_api_key`: Permanently revokes an API key. Applications using this key will immediately lose access.
104
129
 
105
- ### Account (3 tools)
130
+ #### Account & Billing
106
131
 
107
- | Tool | Description |
108
- |------|-------------|
109
- | `get_subscription` | Get the current subscription plan, status, and renewal date |
110
- | `list_plans` | List all available subscription plans with pricing and limits |
111
- | `get_usage` | Get usage statistics for the current billing period (clicks, links, API calls) |
132
+ - `get_subscription`: Gets the current subscription plan, status, and renewal date.
133
+ - `list_plans`: Lists all available subscription plans with pricing and limits.
134
+ - `get_usage`: Gets usage statistics for the current billing period (clicks, links, API calls).
112
135
 
113
136
  ## Environment Variables
114
137
 
115
138
  | Variable | Default | Description |
116
139
  |----------|---------|-------------|
117
- | `ULINK_API_KEY` | -- | API key for authentication (skips browser OAuth flow) |
140
+ | `ULINK_API_KEY` | — | API key for authentication (skips browser OAuth flow) |
118
141
  | `ULINK_API_URL` | `https://api.ulink.ly` | Base URL for the ULink REST API |
119
142
  | `ULINK_FRONTEND_URL` | `https://ulink.ly` | Frontend URL used for the OAuth login flow |
120
- | `ULINK_SUPABASE_ANON_KEY` | -- | Supabase anon key for silent token refresh (without it, expired tokens trigger re-authentication via browser) |
143
+ | `ULINK_SUPABASE_ANON_KEY` | — | Supabase anon key for silent token refresh |
121
144
 
122
145
  ## Requirements
123
146
 
124
147
  - Node.js 18 or later
125
148
 
149
+ ## Resources
150
+
151
+ - [**ULink Documentation**](https://docs.ulink.ly): Learn more about ULink's deep linking platform.
152
+ - [**Model Context Protocol**](https://modelcontextprotocol.io/introduction): Learn more about MCP and its capabilities.
153
+
126
154
  ## License
127
155
 
128
156
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ulinkly/mcp-server",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "ULink MCP Server — Model Context Protocol server for the ULink REST API",
5
5
  "type": "module",
6
6
  "bin": {