Skip to content

Commit 0a76eba

Browse files
PeyGisPeyGis
committed
Merge branch 'PORT-15928-track-status-of-ai-driven-pull-requests' of https://github.com/port-labs/port-docs into PORT-15928-track-status-of-ai-driven-pull-requests
2 parents bab8118 + 431824b commit 0a76eba

38 files changed

+1556
-2083
lines changed

‎docs/actions-and-automations/setup-backend/create-update-entity/create-update-entity.md‎

Lines changed: 108 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
import Tabs from "@theme/Tabs"
2+
import TabItem from "@theme/TabItem"
3+
14
# Create/update entity
25

36
In some cases, we don't want to run complex logic via a workflow or pipeline, but rather want our backend to simply create or update an entity in our software catalog.
@@ -33,15 +36,15 @@ To use this backend type, you will need to define the following fields:
3336
| `team` | The team/s this entity will belong to. |
3437
| `icon` | The icon of the entity. |
3538
| `properties` | The properties of the entity, in `"key":"value"` pairs where the key is the property's identifier, and the value is its value. |
36-
| `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier. |
39+
| `relations` | The relations of the entity, in `"key":"value"` pairs where the key is the relation's identifier, and the value is the related entity's identifier (for single relations) or an array of identifiers (for "many" relations). |
3740

3841
### Use jq to map the entity
3942

4043
All fields in the `mapping` object can be mapped using `jq` expressions, by wrapping the value in double curly braces `{{ }}`.
4144

4245
For example, say we want to assign the initiator of the action to a new entity when it is created, we can take his email from the action run object and assign it to a property named `assignee`:
4346

44-
```json
47+
```json showLineNumbers
4548
{
4649
"identifier": "someTaskEntity",
4750
"title": "Some Task",
@@ -55,3 +58,106 @@ For example, say we want to assign the initiator of the action to a new entity w
5558
:::tip Test your mapping
5659
You can use the `Test JQ` button in the bottom-left corner to test your mapping against the action's schema.
5760
:::
61+
62+
## Map entity relations
63+
64+
When creating or updating entities, you often need to establish relations with other entities. The mapping approach depends on whether you're dealing with single or multiple entity inputs.
65+
66+
67+
<Tabs groupId="relation-mapping" defaultValue="single" values={[
68+
{label: "Single Entity", value: "single"},
69+
{label: "Array Entity", value: "array"},
70+
{label: "Flexible Mapping", value: "flexible"}
71+
]}>
72+
73+
<TabItem value="single">
74+
75+
For a single entity relation, map the entity identifier directly:
76+
77+
```json showLineNumbers
78+
{
79+
"identifier": "myServiceEntity",
80+
"title": "My Service",
81+
"properties": {},
82+
"relations": {
83+
"domain": "{{ .inputs.domain }}"
84+
}
85+
}
86+
```
87+
88+
</TabItem>
89+
90+
<TabItem value="array">
91+
92+
When your action accepts [array entity inputs](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), you need to extract the identifiers from the array using the `map(.identifier)` pattern:
93+
94+
```json showLineNumbers
95+
{
96+
"identifier": "myUserEntity",
97+
"title": "My User",
98+
"properties": {},
99+
"relations": {
100+
"skills": "{{ .inputs.skills | map(.identifier) }}"
101+
}
102+
}
103+
```
104+
105+
:::info Array entity inputs
106+
When users select multiple entities from an [entity array input](/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/user-inputs/entity.md#array), the input contains an array of entity objects. Each object includes both `identifier` and `title` properties, but relations can only reference entity identifiers.
107+
:::
108+
109+
</TabItem>
110+
111+
<TabItem value="flexible">
112+
113+
For maximum flexibility, you can create a conditional mapping that handles both single entity and array entity inputs:
114+
115+
```json showLineNumbers
116+
{
117+
"identifier": "myProjectEntity",
118+
"title": "My Project",
119+
"properties": {},
120+
"relations": {
121+
"dependencies": "{{ .inputs.dependencies | if type == \"array\" then map(.identifier) else .identifier end }}"
122+
}
123+
}
124+
```
125+
126+
This pattern automatically:
127+
- Extracts identifiers from arrays when multiple entities are selected
128+
- Uses the identifier directly when a single entity is selected
129+
130+
</TabItem>
131+
132+
</Tabs>
133+
134+
135+
### Common use cases
136+
137+
Here are some typical scenarios for mapping array relations:
138+
139+
**Mapping skills to a user:**
140+
```json showLineNumbers
141+
"relations": {
142+
"skills": "{{ .inputs.selectedSkills | map(.identifier) }}"
143+
}
144+
```
145+
146+
**Mapping team members to a project:**
147+
```json showLineNumbers
148+
"relations": {
149+
"members": "{{ .inputs.teamMembers | map(.identifier) }}"
150+
}
151+
```
152+
153+
**Mapping dependencies between services:**
154+
```json showLineNumbers
155+
"relations": {
156+
"dependsOn": "{{ .inputs.dependencies | map(.identifier) }}"
157+
}
158+
```
159+
160+
161+
:::info Entity titles in relations
162+
Relations can only reference entity **identifiers**, not titles. Even though entity objects contain both `identifier` and `title` properties, you must always use `.identifier` when mapping to relations.
163+
:::

‎docs/ai-agents/port-mcp-server.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -367,6 +367,194 @@ Refer to the [Claude custom connector documentation](https://support.anthropic.c
367367
</TabItem>
368368
</Tabs>
369369

370+
### Prompts
371+
372+
In Port, you can centrally manage reusable prompts and expose them to your users via the MCP Server. Once defined in Port, these prompts become available in supported MCP clients (for example, Cursor or Claude) where developers and AI agents can discover and run them with the required inputs.
373+
374+
#### Common use cases
375+
376+
- Automate on-call runbooks and incident triage guidance
377+
- Standardize code review or deployment checklists
378+
- Generate structured updates and communications (e.g., incident status, release notes)
379+
380+
#### Setup data model
381+
382+
1. Go to the [Builder page](https://app.getport.io/settings/data-model) of your portal.
383+
384+
2. Click on "+ Blueprint".
385+
386+
3. Click on the `{...}` button in the top right corner, and choose "Edit JSON".
387+
388+
4. Paste the following JSON schema into the editor:
389+
390+
391+
392+
<details>
393+
<summary>Prompt blueprint JSON (click to expand)</summary>
394+
395+
```json showLineNumbers
396+
{
397+
"identifier": "prompt",
398+
"title": "Prompt",
399+
"icon": "Microservice",
400+
"schema": {
401+
"properties": {
402+
"description": {
403+
"type": "string",
404+
"title": "Description"
405+
},
406+
"arguments": {
407+
"items": {
408+
"type": "object",
409+
"properties": {
410+
"name": {
411+
"type": "string",
412+
"description": "The name of the argument parameter"
413+
},
414+
"description": {
415+
"type": "string",
416+
"description": "A description of what this argument is for"
417+
},
418+
"required": {
419+
"type": "boolean",
420+
"description": "Whether this argument is required or optional",
421+
"default": false
422+
}
423+
},
424+
"required": [
425+
"name",
426+
"description"
427+
]
428+
},
429+
"type": "array",
430+
"title": "Arguments"
431+
},
432+
"template": {
433+
"icon": "DefaultProperty",
434+
"type": "string",
435+
"title": "Prompt Template",
436+
"format": "markdown"
437+
}
438+
},
439+
"required": [
440+
"description",
441+
"template"
442+
]
443+
},
444+
"mirrorProperties": {},
445+
"calculationProperties": {},
446+
"aggregationProperties": {},
447+
"relations": {}
448+
}
449+
```
450+
</details>
451+
452+
:::info Where prompts appear
453+
Once this blueprint exists and you create entities for it, prompts will show up in supported MCP clients connected to your Port organization. In clients that surface MCP prompts, you’ll see them listed and ready to run with arguments.
454+
:::
455+
456+
#### Create prompts
457+
458+
Create entities of the `prompt` blueprint for each prompt you want to expose. At minimum, provide `description` and `template`. Optionally add `arguments` to parameterize the prompt.
459+
460+
1. Go to the [Prompts page](https://app.getport.io/prompts) in your portal.
461+
2. Click `Create prompt`.
462+
3. Fill out the form:
463+
- Provide a title and description.
464+
- Write the prompt template (supports markdown).
465+
- Define any `arguments` (optional) with `name`, `description`, and whether they are `required`.
466+
467+
![Create prompt form in Port](/img/ai-agents/PortPromptForm.png)
468+
469+
:::info Template and placeholders
470+
The `template` supports markdown and variable placeholders. Each argument defined in `arguments` is exposed by its `name` and can be referenced as `{{name}}` inside the template. When you run the prompt, the MCP Server collects values for required arguments and substitutes them into the matching `{{}}` placeholders before execution.
471+
:::
472+
473+
#### Examples
474+
475+
<Tabs groupId="prompt-examples" queryString>
476+
<TabItem value="incident-triage" label="Incident triage">
477+
478+
Use placeholders to inject context such as the service, environment, incident, and timeframe.
479+
480+
```markdown showLineNumbers
481+
You are assisting with an incident in the {{service_name}} service ({{environment}}).
482+
Incident ID: {{incident_id}}
483+
484+
For the last {{timeframe}}:
485+
- Summarize critical alerts and recent deploys
486+
- Suggest next steps and owners
487+
- Link relevant dashboards/runbooks
488+
```
489+
490+
Arguments to define: `service_name` (required), `environment` (optional), `incident_id` (required), `timeframe` (optional).
491+
492+
</TabItem>
493+
<TabItem value="scorecard-remediation" label="Scorecard remediation">
494+
495+
Generate tailored remediation steps for failing scorecard rules.
496+
497+
```markdown showLineNumbers
498+
For {{service_name}}, generate remediation steps for failing rules in the "{{scorecard_name}}" scorecard.
499+
500+
For each failing rule:
501+
- What is failing
502+
- Why it matters
503+
- Step-by-step remediation
504+
- Owners and suggested timeline
505+
```
506+
507+
Arguments to define: `service_name` (required), `scorecard_name` (required).
508+
509+
</TabItem>
510+
<TabItem value="on-call-handoff" label="On-call handoff summary">
511+
512+
Summarize on-call context for a team over a time window.
513+
514+
```markdown showLineNumbers
515+
Create an on-call handoff for {{team}} for the last {{timeframe}}.
516+
517+
Include:
518+
- Active incidents and current status
519+
- Top risks and mitigations
520+
- Pending actions and owners
521+
- Upcoming maintenance windows
522+
```
523+
524+
Arguments to define: `team` (required), `timeframe` (required).
525+
526+
</TabItem>
527+
</Tabs>
528+
529+
After creating entities, reconnect or refresh your MCP client; your prompts will be available to run and will prompt for any defined arguments.
530+
531+
#### See prompts in your client
532+
533+
<Tabs groupId="prompt-ui" queryString>
534+
<TabItem value="cursor" label="Cursor">
535+
536+
In Cursor, type "/" to open the prompts list. You'll see all `prompt` entities; selecting one opens an input form for its arguments.
537+
538+
![Prompt list in Cursor](/img/ai-agents/MCPCursorPromptList.png)
539+
540+
When you select a prompt, Cursor renders fields for the defined `arguments`. Required ones are marked and must be provided. The MCP Server substitutes provided values into the matching `{{}}` placeholders in the template at runtime.
541+
542+
![Prompt argument input in Cursor](/img/ai-agents/MCPCursorPromptInput.png)
543+
544+
</TabItem>
545+
<TabItem value="claude" label="Claude">
546+
547+
In Claude, click the "+" button and choose the prompts option to view the list from your Port organization. Selecting a prompt opens a parameter collection flow.
548+
549+
![Prompt list in Claude](/img/ai-agents/MCPClaudePromptList.png)
550+
551+
Claude will ask for any required arguments before running the prompt, and the MCP Server will replace the corresponding `{{}}` placeholders in the template with the provided values.
552+
553+
![Prompt argument input in Claude](/img/ai-agents/MCPClaudePromptInput.png)
554+
555+
</TabItem>
556+
</Tabs>
557+
370558
## Troubleshooting
371559

372560
If you encounter issues while setting up or using the Port MCP Server, expand the relevant section below:

‎docs/api-reference/aggregate-entities-over-time.api.mdx‎

Lines changed: 2 additions & 2 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)