> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

AGENTS.md - AI Documentation Maintenance Guide

This is a hidden guide for AI agents to understand how to maintain and update the AI interfaces documentation in Port Docs.

File Structure​

The AI interfaces documentation files are located in:

  • /docs/agent-management/ - Main documentation files
  • /src/data/mcpTools.js - MCP tool definitions (JSON file)
  • /src/components/ToolsList/ - React component that displays tools from mcpTools.js

Common Tasks​

Update MCP Tools​

To add, update, or remove MCP tools:

  1. Update the file: src/data/mcpTools.js
  2. Ask for clarification: Determine if the tool is for builder only or for both developer and builder roles
  3. The ToolsList component automatically reads from this file and displays tools in the documentation

Tool naming conventions:

  • List tools (list_blueprints, list_entities, etc.): Support optional identifiers parameter to get detailed info for specific items
  • Upsert tools (upsert_blueprint, upsert_entity, etc.): Create or update resources (creates if not exists, updates if exists)
  • Delete tools: Remove resources

Set Feature Beta Status​

When asked to mark a feature as open beta or closed beta, use the appropriate component:

For Open Beta Features​

Use the BetaFeatureNotice component:

import BetaFeatureNotice from '/docs/generalTemplates/_beta_feature_notice.md'

<BetaFeatureNotice id="ai-form" />

Location: Place this after the page title (H1) and before the main content.

For Closed Beta Features​

Use the ClosedBetaFeatureNotice component:

import ClosedBetaFeatureNotice from '/docs/generalTemplates/_closed_beta_feature_notice.md'

<ClosedBetaFeatureNotice id="feature-id" />

Location: Place this after the page title (H1) and before the main content.

ID: Use a specific feature identifier (e.g., "slack-app"). Check /docs/generalTemplates/_closed_beta_feature_notice_defs.js for available IDs and their custom messages. You might need to create a new definition, ask the user for this.

Add New LLM Model​

To add a new LLM model to the documentation:

  1. Identify the model name and providers: Determine the exact model identifier (e.g., gpt-5) and which providers support it (e.g., Anthropic, AWS Bedrock).

  2. Update the main documentation file: Edit docs/port-ai/llm-providers-management/overview.md:

  3. Note about API reference files: The API reference files in docs/api-reference/ (like general-purpose-ai-interactions.api.mdx, invoke-a-specific-agent.api.mdx, etc.) are auto-generated from OpenAPI specifications. These will be updated automatically when the backend API is updated. You don't need to manually edit these files.

Update MCP Installation Instructions​

The MCP installation instructions are maintained in a reusable component that is imported into the installation page.

Location: /docs/generalTemplates/_mcp-installation.md

Usage: This component is imported in docs/agent-management/port-mcp-server/installation.md.

What you could update:

  • Add new client support
  • Update client instructions
  • Update disclaimers/warnings/admonitions

Update Monthly Limits​

When asked to update the monthly quota/limit for AI invocations:

  1. Identify all locations: Search for mentions of monthly limits/quota in the AI interfaces documentation:

    • docs/port-ai/api-interaction.md - Contains rate limits section and example JSON responses

  2. Update text descriptions: Replace the quota number in all text descriptions (e.g., "20 AI invocations per month" → "50 AI invocations per month")

  3. Update example JSON: Update the monthlyLimit value in example JSON responses to match the new limit. Also update remainingQuota to be one less than the limit (e.g., if limit is 50, remainingQuota should be 49)

  4. Files to check:

    • docs/port-ai/api-interaction.md - Lines with "Monthly Quota" section and JSON examples

  5. Search pattern: Look for patterns like:

    • "20 AI invocations per month"
    • "monthlyLimit": 20
    • "Default quota: 20"

Note: The API reference files in docs/api-reference/ are auto-generated from OpenAPI specifications and will be updated automatically when the backend API is updated. You don't need to manually edit these files.

Other Tasks​

For other tasks not listed above, ask for clarification from the user. Once understood, add a new section to the "Common Tasks" section of this file.