manan-smarsh/port-hackathon

Port MCP Server

A Model Context Protocol (MCP) server for interacting with Port's Software Catalog API. This enables GitHub Copilot and other MCP clients to query and interact with your Port entities.

Features

This MCP server provides the following tools:

1. get_entity

Get a specific entity from Port by blueprint and entity identifier.

Use case: Retrieve detailed information about a specific service, product, or any other entity.

Parameters:

• blueprint_identifier (required): The blueprint type (e.g., "service", "product")
• entity_identifier (required): The unique identifier of the entity
• exclude_calculated_properties (optional): Exclude calculated properties from response

2. search_entities

Search for entities using Port's powerful query rules.

Use case: Find entities based on specific criteria, properties, or relations.

Parameters:

• rules (required): Array of search rules with property, operator, and value
• combinator (optional): How to combine rules - "and" or "or" (default: "and")
• exclude_calculated_properties (optional): Exclude calculated properties from response

Example rules:

[
  {
    "property": "$blueprint",
    "operator": "=",
    "value": "service"
  },
  {
    "property": "environment",
    "operator": "=",
    "value": "production"
  }
]

3. find_product_for_service

Helper tool to find the product entity that a service belongs to.

Use case: When you have a service and want to know which product it's part of.

Parameters:

• service_identifier (required): The identifier of the service entity

Returns: Both the service entity and its related product entity.

4. find_services_for_product

Helper tool to find all service entities that belong to a specific product.

Use case: When you want to see all services/applications that compose a product.

Parameters:

• product_identifier (required): The identifier of the product entity

Returns: All service entities related to the product.

Setup

1. Install Dependencies

pip install -r requirements.txt

2. Set Environment Variables

You need Port API credentials to use this server. Get them from your Port organization settings.

export PORT_CLIENT_ID="your-client-id"
export PORT_CLIENT_SECRET="your-client-secret"

3. Configure MCP in GitHub Copilot

Add this server to your MCP configuration file. The location depends on your setup:

For VS Code: Edit ~/Library/Application Support/Code/User/mcp.json (macOS) or equivalent on your OS.

Add the following configuration:

{
  "mcpServers": {
    "port": {
      "command": "python3",
      "args": [
        "/path/to/port-er/port_mcp_server.py"
      ],
      "env": {
        "PORT_CLIENT_ID": "your-client-id",
        "PORT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

For Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "port": {
      "command": "python3",
      "args": [
        "/path/to/port-er/port_mcp_server.py"
      ],
      "env": {
        "PORT_CLIENT_ID": "your-client-id",
        "PORT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

4. Make Script Executable (Optional)

chmod +x port_mcp_server.py

5. Test the Server

You can test the server directly:

export PORT_CLIENT_ID="your-client-id"
export PORT_CLIENT_SECRET="your-client-secret"
python3 port_mcp_server.py

Then send a JSON-RPC request via stdin:

{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}

Usage Examples

Once configured, you can use natural language with GitHub Copilot:

Example 1: Find a Product for a Service

"What product does the service 'auth-service' belong to?"

The assistant will use find_product_for_service with service_identifier: "auth-service".

Example 2: List All Services in a Product

"Show me all services that are part of the 'payments-platform' product"

The assistant will use find_services_for_product with product_identifier: "payments-platform".

Example 3: Get Service Details

"Get the details of the service 'user-api'"

The assistant will use get_entity with blueprint_identifier: "service" and entity_identifier: "user-api".

Example 4: Search for Production Services

"Find all services running in production environment"

The assistant will use search_entities with appropriate rules.

Common Use Cases

1. Finding Service Ownership

Get a service entity to see its owner, team, and repository information:

"Who owns the 'checkout-service'?"

2. Product Discovery

Find which product a service belongs to and get product-level information:

"What product is 'payment-gateway' part of, and who are the product stakeholders?"

3. Service Inventory

List all services for a product to understand its architecture:

"List all microservices in the 'e-commerce' product"

4. Repository Mapping

Find the GitHub repository associated with a service:

"What's the repository URL for 'notification-service'?"

Customization

Adjusting Relation Names

The helper tools (find_product_for_service and find_services_for_product) assume certain relation property names. You may need to adjust these based on your Port configuration:

In port_mcp_server.py, look for:

for rel_key in ["product", "parentProduct", "belongsToProduct"]:

Update this list to match your actual relation property names.

Adding More Helper Tools

You can add additional helper tools by following the pattern:

1. Create a handler function (e.g., handle_your_tool)
2. Add it to the tools list in the tools/list response
3. Add a case for it in the tools/call handler

Troubleshooting

Authentication Issues

• Verify your PORT_CLIENT_ID and PORT_CLIENT_SECRET are correct
• Check that your Port credentials have the necessary permissions

Entity Not Found

• Verify the blueprint identifier matches your Port configuration
• Check that the entity identifier exists in your Port catalog

Relation Properties Not Found

• The relation property names might be different in your Port setup
• Check your Port blueprint configuration for the actual relation property names

API Reference

Port API Endpoints Used

• POST /v1/auth/access_token - Authentication
• GET /v1/blueprints/{blueprint}/entities/{entity} - Get entity
• POST /v1/entities/search - Search entities

For more details, see:

• Port API - Get Entity
• Port API - Search Entities

License

MIT