You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: best_practices.md
+15-29Lines changed: 15 additions & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,19 @@
1
1
# Port documentation style guide
2
2
3
+
___
4
+
5
+
**Header capitalization rules:** Use sentence case for headers with only the first word capitalized.
6
+
7
+
❌ "## Sync Approaches And Methods"
8
+
✅ "## Sync approaches and methods"
9
+
10
+
Note: Well-known product names such as Lambda, Kubernetes, ArgoCD, etc. should follow their standard capitalization rules and styling.
11
+
12
+
❌ "aws"
13
+
✅ "AWS"
14
+
15
+
___
16
+
3
17
This document details guidelines for contributing to Port's documentation, and demonstrates how to correctly write and review documentation content.
4
18
5
19
<b>Pattern 1: Always standardize collapsible details with bold titles and "(click to expand)" for consistency and usability across docs.</b>
@@ -208,34 +222,6 @@ Example code after:
208
222
209
223
___
210
224
211
-
<b>Pattern 8: Use sentence case for headers with only the first word capitalized, and ensure links follow capitalization rules based on their position in the sentence.</b>
212
-
213
-
Example code before:
214
-
215
-
```
216
-
## Sync Approaches And Methods
217
-
218
-
Check out our [Guide](docs/guide.md) for more information.
219
-
```
220
-
221
-
Example code after:
222
-
223
-
```
224
-
## Sync approaches and methods
225
-
226
-
Check out our [guide](docs/guide.md) for more information.
227
-
```
228
-
229
-
Note: Well-known product names such as Lambda, Kubernetes, ArgoCD, etc. should follow their standard capitalization rules and styling.
230
-
231
-
<details><summary>Examples for relevant past discussions:</summary>
232
-
233
-
<!-- Add links to relevant PR discussions here -->
234
-
235
-
</details>
236
-
237
-
___
238
-
239
225
<b>Pattern 9: Use "We" language instead of commanding "You" language to create a collaborative, guiding tone rather than issuing commands.</b>
240
226
241
227
Example code before:
@@ -699,4 +685,4 @@ Before submitting your contribution, review it against this checklist:
699
685
-[ ] Tone is consistent with Port's documentation style
700
686
-[ ] Content is organized logically
701
687
-[ ] Technical terms are explained or linked to definitions
You can use Port's MCP to find the use cases that will be valuable to you. Try using this prompt: "think of creative prompts I can use to showcase the power of Port's MCP, based on the data available in Port"
118
119
119
-
120
-
## Installing Port MCP
121
-
122
-
Installing Port's MCP is simple. Follow the instructions for your preferred tool, or learn about the archived local MCP server.
123
-
124
-
<TabsgroupId="mcp-setup"queryString>
125
-
<TabItemvalue="cursor"label="Cursor">
126
-
To connect Cursor to Port's remote MCP, follow these steps:
127
-
128
-
1.**Go to Cursor settings, click on Tools & Integrations, and add a new MCP server**
129
-
130
-
131
-
132
-
2.**Add the above configuration**
133
-
134
-
Use the appropriate configuration for your region:
In some cases, after clicking "Accept" in the authentication popup, the window won't get closed but the connection is established successfully. You can safely close the window.
173
-
174
-
If you still don't see the tool, try it a couple of times. We are aware of this behavior and working to improve it.
175
-
:::
176
-
177
-
</TabItem>
178
-
<TabItemvalue="vscode"label="VSCode">
179
-
To connect VSCode to Port's remote MCP server, follow these detailed steps. For complete instructions, refer to the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
180
-
181
-
:::info VSCode MCP requirements
182
-
Before proceeding, ensure your VS Code is updated to the latest version and that MCP is enabled for your GitHub organization. You may need to enable "Editor preview features" under Settings > Code, planning, and automation > Copilot via admin access from your organization.
183
-
:::
184
-
185
-
:::tip Prerequisites
186
-
This configuration uses the open-source `mcp-remote` package, which requires Node.js to be installed on your system. Before using the configuration, ensure Node.js is available by running:
187
-
188
-
```bash
189
-
npx -y mcp-remote --help
190
-
```
191
-
192
-
If you encounter errors:
193
-
-**Missing Node.js**: Install Node.js from [nodejs.org](https://nodejs.org/)
194
-
-**Network issues**: Check your internet connection and proxy settings
195
-
-**Permission issues**: You may need to run with appropriate permissions
196
-
:::
197
-
198
-
:::warning VSCode action tool issue
199
-
In some versions of VS Code, the MCP server might not start or return an error in the chat because of a configuration issue with the action related tools. To deal with it, [deselect](./available-tools#select-which-tools-to-use) the tools `create_action`, `update_action`, and `delete_action`.
200
-
This is relevant for cases where you see an error like this one:
201
-
```
202
-
Failed to validate tool mcp_port_create_action: Error: tool parameters array type must have items. Please open a Github issue for the MCP server or extension which provides this tool
203
-
```
204
-
:::
205
-
206
-
**Step 1: Configure MCP Server Settings**
207
-
208
-
1. Open VS Code settings
209
-
2. Search for "MCP: Open user configuration" (or follow the instructions on a workspace installation)
210
-
3. Add the server configuration using the appropriate configuration for your region:
211
-
212
-
<Tabs>
213
-
<TabItemvalue="eu"label="EU">
214
-
```json showLineNumbers
215
-
{
216
-
"mcpServers": {
217
-
"port-vscode-eu": {
218
-
"command": "npx",
219
-
"args": [
220
-
"-y",
221
-
"mcp-remote",
222
-
"https://mcp.port.io/v1"
223
-
]
224
-
}
225
-
}
226
-
}
227
-
```
228
-
</TabItem>
229
-
<TabItemvalue="us"label="US">
230
-
```json showLineNumbers
231
-
{
232
-
"mcpServers": {
233
-
"port-vscode-us": {
234
-
"command": "npx",
235
-
"args": [
236
-
"-y",
237
-
"mcp-remote",
238
-
"https://mcp.us.port.io/v1"
239
-
]
240
-
}
241
-
}
242
-
}
243
-
```
244
-
</TabItem>
245
-
</Tabs>
246
-
247
-
**Step 2: Start the MCP Server**
248
-
249
-
1. After adding the configuration, click on "Start" to initialize the MCP server
250
-
2. If you don't see the "Start" button, ensure:
251
-
- Your VS Code version is updated to the latest version
252
-
- MCP is enabled for your GitHub organization
253
-
- "Editor preview features" is enabled under Settings > Code, planning, and automation > Copilot
254
-
255
-
**Step 3: Verify Connection**
256
-
257
-
1. Once started, you should see the number of available tools displayed
258
-
2. If you don't see the tools count:
259
-
- Click on "More" to expand additional options
260
-
- Select "Show output" to view detailed logs
261
-
- Check the output panel for any error messages or connection issues
262
-
263
-
**Step 4: Access Port Tools**
264
-
265
-
1. Start a new chat session in VS Code
266
-
2. Click on the tools icon in the chat interface
267
-
3. You should now see Port tools available for use
To connect Claude to Port's remote MCP, you need to create a custom connector. This process does not require a client ID. For detailed instructions, refer to the [official Anthropic documentation on custom connectors](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).
274
-
275
-
When prompted for the remote MCP server URL, use the appropriate URL for your region:
276
-
277
-
<Tabs>
278
-
<TabItemvalue="eu"label="EU">
279
-
```
280
-
https://mcp.port.io/v1
281
-
```
282
-
</TabItem>
283
-
<TabItemvalue="us"label="US">
284
-
```
285
-
https://mcp.us.port.io/v1
286
-
```
287
-
</TabItem>
288
-
</Tabs>
289
-
</TabItem>
290
-
<TabItemvalue="local-mcp"label="Local MCP">
291
-
The local MCP server is an open-source project that you can run on your own infrastructure. It offers a similar set of capabilities, but requires manual setup and maintenance.
292
-
293
-
While you can use it, we are no longer supporting it and are not tracking the project issues and activities.
294
-
295
-
<h2>Prerequisites</h2>
296
-
297
-
- A Port.io account with appropriate permissions.
298
-
- Your Port credentials (Client ID and Client Secret). You can create these from your Port.io dashboard under Settings > Credentials.
299
-
300
-
<h2>Installation</h2>
301
-
302
-
The Port MCP Server can be installed using Docker or `uvx` (a package manager for Python). While the setup is straightforward, the specifics can vary based on your chosen MCP client (Claude, Cursor, VS Code, etc.).
303
-
304
-
:::info Detailed Installation Guide
305
-
For comprehensive, step-by-step installation instructions for various platforms and methods (Docker, UVX), please refer to the **[Port MCP Server GitHub README](https://github.com/port-labs/port-mcp-server)**.
306
-
The README provides the latest configuration details and examples for different setups.
0 commit comments