dir-mcp

MCP Server for Directory

Model Context Protocol (MCP) server for working with OASF agent records.

Tools

agntcy_oasf_list_versions

Lists all available OASF schema versions supported by the server.

Input: None
Output: available_versions ([]string), default_version (string), count (int), error_message (string)

agntcy_oasf_get_schema

Retrieves the complete OASF schema JSON content for the specified version.

Input: version (string) - OASF schema version (e.g., "0.7.0", "0.8.0", "1.0.0")
Output: version (string), schema (string), available_versions ([]string), error_message (string)

agntcy_oasf_get_schema_skills

Retrieves skills from the OASF schema with hierarchical navigation support.

Input:

• version (string, required) - OASF schema version (e.g., "0.7.0")
• parent_skill (string, optional) - Parent skill to filter sub-skills

Output: skills (array), version, parent_skill, available_versions, error_message

Without parent_skill, returns top-level skill categories. With parent_skill, returns direct sub-skills under that parent. Each skill includes name, caption, and id fields.

agntcy_oasf_get_schema_domains

Retrieves domains from the OASF schema with hierarchical navigation support.

Input:

• version (string, required) - OASF schema version (e.g., "0.7.0")
• parent_domain (string, optional) - Parent domain to filter sub-domains

Output: domains (array), version, parent_domain, available_versions, error_message

Without parent_domain, returns top-level domain categories. With parent_domain, returns direct sub-domains under that parent. Each domain includes name, caption, and id fields.

agntcy_oasf_validate_record

Validates an OASF agent record against the OASF schema.

Input: record_json (string)
Output: valid (bool), schema_version (string), validation_errors ([]string), error_message (string)

agntcy_dir_push_record

Pushes an OASF agent record to a Directory server.

Input: record_json (string) - OASF agent record JSON
Output: cid (string), server_address (string), error_message (string)

This tool validates and uploads the record to the configured Directory server. It returns the Content Identifier (CID) and the server address where the record was stored.

agntcy_dir_search_local

Searches for agent records on the local directory node using structured query filters.

Input (all optional):

• limit (uint32) - Maximum results to return (default: 100, max: 1000)
• offset (uint32) - Pagination offset (default: 0)
• names ([]string) - Agent name patterns (supports wildcards)
• versions ([]string) - Version patterns (supports wildcards)
• skill_ids ([]string) - Skill IDs (exact match only)
• skill_names ([]string) - Skill name patterns (supports wildcards)
• locators ([]string) - Locator patterns (supports wildcards)
• module_names ([]string) - Module name patterns (supports wildcards)
• module_ids ([]string) - Module IDs (exact match only)
• domain_ids ([]string) - Domain IDs (exact match only)
• domain_names ([]string) - Domain name patterns (supports wildcards)
• authors ([]string) - Author name patterns (supports wildcards)
• created_ats ([]string) - Created_at timestamp patterns (supports wildcards)
• schema_versions ([]string) - Schema version patterns (supports wildcards)

Output:

• record_cids ([]string) - Array of matching record CIDs
• count (int) - Number of results returned
• has_more (bool) - Whether more results are available
• error_message (string) - Error message if search failed

Wildcard Patterns:

• * - Matches zero or more characters
• ? - Matches exactly one character
• [abc] - Matches any character in the brackets

Examples:

// Find all Python-related agents
{
  "skill_names": ["*python*", "*Python*"]
}

// Find specific version
{
  "names": ["my-agent"],
  "versions": ["v1.*"]
}

// Complex search with pagination
{
  "skill_names": ["*machine*learning*"],
  "locators": ["docker-image:*"],
  "limit": 50,
  "offset": 0
}

Note: Multiple filters are combined with OR logic. Requires Directory server configuration via environment variables.

agntcy_dir_pull_record

Pulls an OASF agent record from the local Directory node by its CID (Content Identifier).

Input:

• cid (string) - Content Identifier of the record to pull (required)

Output:

• record_data (string) - The record data (JSON string)
• error_message (string) - Error message if pull failed

Example:

{
  "cid": "bafkreiabcd1234567890"
}

Note: The pulled record is content-addressable and can be validated against its hash. Requires Directory server configuration via environment variables.

agntcy_dir_verify_name

Verifies that a record's name is owned by the domain it claims. This tool checks that the record was signed with a key published in the domain's well-known JWKS file (/.well-known/jwks.json).

Input (at least one required):

• cid (string) - Content Identifier (CID) of the record to verify
• name (string) - Human-readable name of the record (e.g., "https://example.com/my-agent")
• version (string, optional) - Version to verify (e.g., "v1.0.0"). If omitted, verifies the latest version.

Output:

• verified (bool) - Whether the name ownership was verified
• domain_verification (object, optional) - Details about the domain verification:
  • domain (string) - The domain that was verified
  • method (string) - Verification method used (e.g., "wellknown")
  • matched_key_id (string) - The key ID that matched from the domain's JWKS
  • verified_at (string) - Timestamp when verification occurred
• error_message (string) - Error message if verification failed

Use when: You want to verify that an agent record was actually published by the domain owner. Records must have URL-based names (starting with http:// or https://) for domain verification to work.

agntcy_dir_verify_record

Verifies the digital signature of a record in the Directory by its CID. This tool performs a server-side verification of the record's integrity and authenticity.

Input:

• cid (string, required) - Content Identifier (CID) of the record to verify

Output:

• success (bool) - Whether the signature verification was successful
• message (string) - Status message indicating trust level
• signers (array, optional) - Information about verified signers:
  • identity (string) - Signer identity
  • issuer (string) - Certificate issuer
• error (string) - Error message if verification request failed

Use when: You want to ensure a record has been properly signed and hasn't been tampered with.

agntcy_oasf_import_record

Imports data from other formats (MCP, A2A) to OASF agent record format.

Input:

• source_data (string, required) - JSON string of the source data to import
• source_format (string, required) - Source format: "mcp" or "a2a"

Output:

• record_json (string) - The imported OASF record (JSON string)
• error_message (string) - Error message if import failed

Note: The resulting record requires domain and skill enrichment. For the complete workflow with automatic enrichment and validation, use the import_record prompt instead.

agntcy_oasf_export_record

Exports an OASF agent record to other formats (A2A, GitHub Copilot).

Input:

• record_json (string, required) - JSON string of the OASF agent record to export
• target_format (string, required) - Target format: "a2a" or "ghcopilot"

Output:

• exported_data (string) - The exported data in the target format (JSON string)
• error_message (string) - Error message if export failed

Note: For the complete workflow with validation, use the export_record prompt instead.

Prompts

MCP Prompts are guided workflows that help you accomplish tasks. The server exposes the following prompts:

create_record

Analyzes the current directory codebase and automatically generates a complete, valid OASF agent record. The AI examines the repository structure, documentation, and code to determine appropriate skills, domains, and metadata.

Input (optional):

• output_path (string) - Where to output the record:
  • File path (e.g., "agent.json") to save to file
  • "stdout" to display only (no file saved)
  • Empty or omitted defaults to "stdout"
• schema_version (string) - OASF schema version to use (defaults to "1.0.0")

Use when: You want to automatically generate an OASF record for the current directory's codebase.

validate_record

Guides you through validating an existing OASF agent record. Reads a file, validates it against the schema, and reports any errors.

Input (required): record_path (string) - Path to the OASF record JSON file to validate

Use when: You have an existing record file and want to check if it's valid.

push_record

Complete workflow for validating and pushing an OASF record to the Directory server. Validates the record first, then pushes it to the configured server and returns the CID.

Input (required): record_path (string) - Path to the OASF record JSON file to validate and push

Use when: You're ready to publish your record to a Directory server.

search_records

Guided workflow for searching agent records using free-text queries. This prompt automatically translates natural language queries into structured search parameters by leveraging OASF schema knowledge.

Input (required): query (string) - Free-text description of what agents you're looking for

What it does:

1. Retrieves the OASF schema to understand available skills and domains
2. Analyzes your free-text query
3. Translates it to appropriate search filters (names, skills, locators, etc.)
4. Executes the search using agntcy_dir_search_local
5. Extracts and displays ALL CIDs from the search results (from the record_cids field)
6. Provides summary and explanation of search strategy

Important: The prompt explicitly instructs the AI to extract the record_cids array from the tool response and display every CID clearly. The response will always include actual CID values, never placeholders.

Example queries:

• "find Python agents"
• "agents that can process images"
• "docker-based translation services"
• "GPT models version 2"
• "agents with text completion skills"

Use when: You want to search using natural language rather than structured filters. The AI will map your query to OASF taxonomy.

Note: For direct, structured searches, use the agntcy_dir_search_local tool instead.

pull_record

Guided workflow for pulling an OASF agent record from the Directory by its CID.

Input:

• cid (string, required) - Content Identifier (CID) of the record to pull
• output_path (string, optional) - Where to save the record:
  • File path (e.g., "record.json") to save to file
  • "stdout" or empty to display only (no file saved)
  • Empty or omitted defaults to "stdout"

What it does:

1. Validates the CID format
2. Calls agntcy_dir_pull_record with the CID
3. Displays the record data
4. Parses and formats the record JSON for readability
5. Saves to file if output_path is specified
6. Optionally validates the record using agntcy_oasf_validate_record

Use when: You have a CID and want to retrieve the full record. The pulled record is content-addressable and can be validated against its hash.

import_record

Complete guided workflow for importing data from other formats to OASF.

Input:

• source_data_path (string, required) - Path to the source data file to import
• source_format (string, required) - Source format: "mcp" or "a2a"
• output_path (string, optional) - Where to save the imported OASF record (file path or empty for stdout)
• schema_version (string, optional) - OASF schema version to use for validation (defaults to "0.8.0")

What it does: Reads the source file, converts it to OASF format, enriches domains and skills using the OASF schema, validates the result, and optionally saves to file.

Use when: You want to import MCP servers or A2A cards into the OASF format. This handles all the complexity automatically.

export_record

Complete guided workflow for exporting an OASF record to other formats.

Input:

• record_path (string, required) - Path to the OASF record JSON file to export
• target_format (string, required) - Target format: "a2a" or "ghcopilot"
• output_path (string, optional) - Where to save the exported data (file path or empty for stdout)

What it does: Reads the OASF record, validates it, converts it to the target format, and optionally saves to file.

Use when: You want to export OASF records to A2A cards or GitHub Copilot MCP configurations.

Setup

The MCP server runs via the dirctl CLI tool, which can be obtained as a pre-built binary or Docker image. For installation methods, see the Directory CLI documentation.

1. Binary

Add the MCP server to your IDE's MCP configuration using the absolute path to the dirctl binary.

Example Cursor configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "dir-mcp-server": {
      "command": "/absolute/path/to/dirctl",
      "args": ["mcp", "serve"]
    }
  }
}

2. Docker Image

Add the MCP server to your IDE's MCP configuration using Docker.

Example Cursor configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "dir-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/agntcy/dir-ctl:latest",
        "mcp",
        "serve"
      ]
    }
  }
}

Environment Variables

The following environment variables can be used with both binary and Docker configurations:

Directory Client Configuration

• DIRECTORY_CLIENT_SERVER_ADDRESS - Directory server address (default: 0.0.0.0:8888)
• DIRECTORY_CLIENT_AUTH_MODE - Authentication mode: none, x509, jwt, token, github
• DIRECTORY_CLIENT_SPIFFE_TOKEN - Path to SPIFFE token file (for token authentication)
• DIRECTORY_CLIENT_GITHUB_TOKEN - GitHub Personal Access Token (for GitHub authentication)
• DIRECTORY_CLIENT_TLS_SKIP_VERIFY - Skip TLS verification (set to true if needed)

GitHub Authentication

Recommended: Personal Access Token (PAT)

For MCP servers running in your IDE, we recommend using a GitHub Personal Access Token (PAT). Unlike OAuth tokens that expire every 8 hours, PATs provide long-lived authentication without requiring frequent re-login and IDE restarts.

Setup Steps:

1. Create a GitHub PAT at GitHub Settings > Personal access tokens
   • Select scopes: user:email and read:org
   • Set expiration: 90 days, 1 year, or no expiration
2. Add the token to your MCP configuration (see examples below)
3. Set DIRECTORY_CLIENT_AUTH_MODE to "github"

Alternative: OAuth Token

If you prefer shorter-lived credentials, you can use OAuth tokens obtained via dirctl auth login. Note that OAuth tokens expire every 8 hours, requiring you to re-authenticate and restart your IDE for the MCP server to pick up the new token.

Security Note: Never commit tokens to version control. IDE configuration files are local and protected by OS file permissions.

OASF Validation Configuration

• OASF_API_VALIDATION_SCHEMA_URL - OASF schema URL for validation and schema operations

  • Required - The MCP server requires this environment variable to be set
  • URL of the OASF schema server to use for validation and schema retrieval
  • If not set, the server will fail to start with an error
  • Example: https://schema.oasf.outshift.com

  This URL is used for:

  • Validating OASF agent records
  • Retrieving schema content, versions, skills, and domains
  • All schema-related operations

Example - Basic configuration (Cursor):

{
  "mcpServers": {
    "dir-mcp-server": {
      "command": "/absolute/path/to/dirctl",
      "args": ["mcp", "serve"],
      "env": {
        "OASF_API_VALIDATION_SCHEMA_URL": "https://schema.oasf.outshift.com",
        "DIRECTORY_CLIENT_SERVER_ADDRESS": "localhost:8888"
      }
    }
  }
}

Example - Use custom OASF schema server (Cursor):

{
  "mcpServers": {
    "dir-mcp-server": {
      "command": "/absolute/path/to/dirctl",
      "args": ["mcp", "serve"],
      "env": {
        "OASF_API_VALIDATION_SCHEMA_URL": "http://localhost:8080",
        "DIRECTORY_CLIENT_SERVER_ADDRESS": "localhost:8888"
      }
    }
  }
}

Example - Use GitHub authentication with PAT (Cursor):

{
  "mcpServers": {
    "dir-mcp-server": {
      "command": "/absolute/path/to/dirctl",
      "args": ["mcp", "serve"],
      "env": {
        "DIRECTORY_CLIENT_SERVER_ADDRESS": "prod.gateway.ads.outshift.io:443",
        "DIRECTORY_CLIENT_AUTH_MODE": "github",
        "DIRECTORY_CLIENT_GITHUB_TOKEN": "<your_personal_access_token>"
      }
    }
  }
}

Example - Use GitHub authentication with OAuth token (Cursor):

{
  "mcpServers": {
    "dir-mcp-server": {
      "command": "/absolute/path/to/dirctl",
      "args": ["mcp", "serve"],
      "env": {
        "DIRECTORY_CLIENT_SERVER_ADDRESS": "prod.gateway.ads.outshift.io:443",
        "DIRECTORY_CLIENT_AUTH_MODE": "github"
      }
    }
  }
}

Before starting the MCP server with OAuth token configuration, authenticate using dirctl auth login. The server will automatically load your cached token from ~/.config/dirctl/auth-token.json. Remember to re-authenticate and restart your IDE when the token expires (every 8 hours).

Note: After changing the configuration, fully restart your IDE (e.g., quit and reopen Cursor) for the MCP server to reload with the new settings.

Usage in Cursor Chat

Using Tools - Ask naturally, AI calls tools automatically:

• "List available OASF schema versions"
• "Validate this OASF record at path: /path/to/record.json"
• "Search for Python agents with image processing"
• "Push this record: [JSON]"
• "Verify the name ownership for this CID: baearei..."
• "Verify the signature of this record: baearei..."
• "Import this A2A card to OASF format: [JSON]"
• "Export this OASF record to A2A format: [JSON]"

Using Prompts - For guided workflows reference prompts with:

• /dir-mcp-server/create_record - Generate OASF record from current directory
• /dir-mcp-server/validate_record - Validate an existing OASF record file
• /dir-mcp-server/push_record - Validate and push record to Directory
• /dir-mcp-server/search_records - Search with natural language queries
• /dir-mcp-server/pull_record - Pull record by CID
• /dir-mcp-server/import_record - Import from MCP/A2A with enrichment
• /dir-mcp-server/export_record - Export OASF to other formats

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. For detailed contributing guidelines, please see CONTRIBUTING.md.

License

Distributed under the Apache-2.0 License. See LICENSE for more information.