diff --git a/content/docs/graph/concepts/event-routing.mdx b/content/docs/graph/concepts/event-routing.mdx index 19b5fdd..831f2b8 100644 --- a/content/docs/graph/concepts/event-routing.mdx +++ b/content/docs/graph/concepts/event-routing.mdx @@ -216,7 +216,7 @@ Full CloudEvents 1.0 format with complete event details. Use for real-time monit ```json { "specversion": "1.0", - "type": "Konnektr.DigitalTwins.Twin.Update", + "type": "Konnektr.Graph.Twin.Update", "source": "https://my-instance.api.graph.konnektr.io", "id": "550e8400-e29b-41d4-a716-446655440000", "time": "2025-01-20T10:30:00Z", @@ -236,7 +236,7 @@ Full CloudEvents 1.0 format with complete event details. Use for real-time monit | Attribute | Description | |-----------|-------------| | `specversion` | CloudEvents version (always "1.0") | -| `type` | Event type (e.g., `Konnektr.DigitalTwins.Twin.Update`) | +| `type` | Event type (e.g., `Konnektr.Graph.Twin.Update`) | | `source` | URI of the Konnektr Graph instance | | `id` | Unique event identifier (UUID) | | `time` | ISO 8601 timestamp when event occurred | diff --git a/content/docs/graph/concepts/mcp-server.mdx b/content/docs/graph/concepts/mcp-server.mdx index a5336e6..4bacd84 100644 --- a/content/docs/graph/concepts/mcp-server.mdx +++ b/content/docs/graph/concepts/mcp-server.mdx @@ -1,135 +1,99 @@ --- -title: MCP Server -icon: Server +title: Model Context Protocol (MCP) Server +icon: Cpu --- -The AgeDigitalTwins MCP Server allows LLMs to interact with a semantic graph memory based on Azure Digital Twins (DTDL) and Apache AGE (PostgreSQL). This enables building "self-healing" AI memory systems that enforce data schema and support hybrid vector search. +# Connecting to the Model Context Protocol (MCP) Server -## Authentication & Authorization +The Model Context Protocol (MCP) provides a standardized way for AI models and agents to interact with external tools and services. Konnektr Graph includes a built-in MCP server that exposes the Digital Twin capabilities as a set of tools that an AI agent can use. -The MCP Server uses OAuth 2.1 with JWT Bearer tokens for authentication and policy-based authorization for access control. +This allows an AI to directly query, create, update, and manage your digital twin graph in a structured and validated way. -### Requirements +## Endpoint and Connection -To access the MCP server, clients must provide: +The shared MCP server is a single endpoint for all Konnektr Graph instances. You specify which graph instance you want to connect to by using the `resource_id` query parameter. -1. **OAuth Scope**: `mcp:tools` - Required by the MCP OAuth 2.1 specification (RFC 9728) -2. **Permission**: `mcp/*` - Application-level permission to access MCP tools - -### How It Works - -``` -Request with JWT Token - ↓ -1. JWT Authentication - Validates token from Auth0 - ↓ -2. OAuth Scope Check - Verifies "mcp:tools" scope (MCP-specific) - ↓ -3. Permission Check - Verifies "mcp/*" permission (policy-based) - ↓ -4. Tool Execution +**Endpoint URL:** ``` - -For detailed information about the authorization architecture, see [Authorization Architecture](/docs/advanced-topics/authorization-architecture). - -### Configuration - -```json -{ - "Authentication": { - "Enabled": true, - "Authority": "https://auth.konnektr.io", - "Audience": "https://graph.konnektr.io", - "Issuer": "https://auth.konnektr.io/" - }, - "Authorization": { - "Enabled": true, - "Provider": "Claims", - "PermissionsClaimName": "permissions", - "RequiredScopes": ["mcp:tools"], - "ScopesSupported": ["mcp:tools", "mcp:resources"] - } -} +https://mcp.graph.konnektr.io/mcp?resource_id={your-resource-id} ``` -### OAuth Discovery +- **`{your-resource-id}`**: The unique identifier for your Konnektr Graph instance. +- **Transport**: The server supports `http_stream` (also known as Server-Sent Events or SSE). -The server implements RFC 9728 (Protected Resource Metadata) at `/.well-known/oauth-protected-resource` for OAuth client discovery. +## Authentication -## Features +The MCP server uses **OAuth 2.1 with Dynamic Client Registration**, as described in the [official MCP documentation](https://modelcontextprotocol.io/docs/tutorials/security/authorization). -### 1. Model Management -The server provides tools to understand the semantic data model: -- `GetModels`: Returns a lightweight summary of available models (ID and Display Name). Use this to explore the domain. -- `GetModel`: Returns the **fully flattened** DTDL definition of a specific model. This includes all inherited properties, relationships, and components from base models, giving the LLM a complete view of the schema without needing to traverse the inheritance hierarchy manually. -- `SearchModels`: Performs a hybrid search (semantic vector + lexical keyword) to find relevant models. -- `CreateModels`: Allows creating new DTDL models. -- `UpdateModelEmbedding`: Updates the vector embedding for a model to enable semantic search. +This is a secure, user-friendly approach that **does not require you to manually manage `client_id` or `client_secret`**. When your MCP client connects for the first time, it will be guided through a one-time browser-based authorization flow to grant access. -### 2. Cypher Query Generation -The server is designed to help LLMs generate optimized Cypher queries for Apache AGE. -- **Nodes**: Digital Twins always have the `:Twin` label. Models have the `:Model` label. -- **Inheritance**: To query twins of a specific model *and* its sub-types, use the optimized pattern: - ```cypher - MATCH (m1:Model {id: 'dtmi:example:TargetModel;1'})<-[:_extends*0..]-(m2:Model) - WITH collect(m2.id) AS model_ids - MATCH (t:Twin) - WHERE t.`$metadata`.`$model` IN model_ids - RETURN t - ``` -- **Validation**: The system enforces DTDL schema validation on all writes (`CreateOrReplaceDigitalTwin`, `UpdateDigitalTwin`), ensuring data integrity. +## Connecting with `npx mcp-remote` -### 3. Vector / Hybrid Search -The system supports semantic search using `pgvector`. -- **Definition**: Vector properties are defined in DTDL as `Array` with a semantic description (e.g., "embedding"). -- **Search Tool**: Use the `HybridMemorySearch` tool to perform similarity searches combined with metadata filtering. -- **Manual Query**: - ```cypher - MATCH (t:Twin) - WHERE t.`$metadata`.`$model` = 'dtmi:example:MyModel;1' - RETURN t - ORDER BY l2_distance(t.embedding, [0.1, 0.2, ...]::vector) ASC - LIMIT 5 - ``` +For MCP clients that do not natively support remote HTTP endpoints or the OAuth 2.1 flow (e.g., some versions of Claude Desktop), you can use the `mcp-remote` tool to create a secure local proxy. -### 4. Graph Exploration -- `ExploreGraphNeighborhood`: Quickly retrieve the subgraph surrounding a specific twin to understand context. +### Client Configuration Example (Claude Desktop) -## Hosted MCP Server +Here is an example of how to configure a compatible MCP client, such as Claude Desktop: -Konnektr Graph provides a fully managed, hosted MCP server for every "Standard" tier instance. - -- **URL Format**: `https://{resource-id}.mcp.graph.konnektr.io` -- **Authentication**: Uses the same OAuth 2.1 credentials and JWT tokens as the Konnektr API. -- **Transport**: Supports both `http` and `sse` (Server-Sent Events) for real-time streaming. -- **Demo Instance**: A public demo is available at `demo.mcp.graph.konnektr.io` for testing without authentication. - -For a step-by-step tutorial on building AI-driven memory systems, see the [How to Build a Business Twin with MCP](/docs/how-to-guides/mcp-server-business-twin) guide. - -## Usage Guide for Agents +```json +{ + "mcpServers": { + "konnektr": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id"] + } + } +} +``` +The client only needs to know the URL and that the authentication type is `oauth2`. The rest is handled automatically. -### Prerequisites +### Claude CLI Configuration -Before using the MCP server, ensure you have: -- Valid OAuth 2.1 JWT token from Auth0 -- `mcp:tools` scope in your token -- `mcp/*` permission in your token claims +To add the Konnektr Graph MCP server to your Claude CLI, use the following command: -### Workflow +```bash +claude mcp add konnektr --transport http https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id +``` -1. **Understand the Domain**: Call `GetModels` to see what types of entities exist. -2. **Inspect Schema**: Call `GetModel(modelId)` to understand the properties and relationships of a specific type. -3. **Search**: - - Use `HybridMemorySearch` if you have a vector or need semantic similarity. - - Use `ExploreGraphNeighborhood` to walk the graph. - - For complex queries, generate Cypher using the `GenerateQueryPrompt` guidance. +This command sets up the connection named `konnektr` using HTTP transport to the specified MCP endpoint. -### Error Handling -The server returns standard OAuth 2.1 error responses: +### Gemini CLI Configuration +For Gemini CLI, you can add the MCP server with a similar command: -- **401 Unauthorized**: Missing or invalid JWT token -- **403 Forbidden (insufficient_scope)**: Missing required OAuth scope -- **403 Forbidden**: Missing required permission +```bash +gemini mcp add konnektr --transport http https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id +``` -All responses include the `/.well-known/oauth-protected-resource` URL for client configuration discovery. +## Available Tools + +When an AI agent connects to the MCP server, it gains access to a suite of tools to interact with the digital twin graph. + +### Model Management +- **`create_model`**: Creates a new DTDL model. +- **`delete_model`**: Deletes a DTDL model. +- **`get_model`**: Retrieves the full definition of a single DTDL model. +- **`list_models`**: Lists all DTDL models in the graph. +- **`search_models`**: Searches for DTDL models. + +### Digital Twin Management +- **`create_or_replace_digital_twin`**: Creates or replaces a digital twin. +- **`delete_digital_twin`**: Deletes a digital twin. +- **`get_digital_twin`**: Retrieves a digital twin by its ID. +- **`update_digital_twin`**: Updates a twin's properties using a JSON Patch. +- **`search_digital_twins`**: Performs a semantic search for twins. + +### Relationship Management +- **`create_or_replace_relationship`**: Creates or replaces a relationship between two twins. +- **`delete_relationship`**: Deletes a relationship. +- **`get_relationship`**: Retrieves a specific relationship. +- **`list_relationships`**: Lists all outgoing relationships from a twin. +- **`update_relationship`**: Updates a relationship's properties using a JSON Patch. + +### Querying +- **`query_digital_twins`**: Executes a Cypher query against the graph. + +## See Also +- [How-to Guide: Build a Business Twin with MCP](/how-to-guides/mcp-server-business-twin) +- [Digital Twins Definition Language (DTDL)](/concepts/dtdl) +- [Querying the Graph](/concepts/querying) diff --git a/content/docs/graph/concepts/meta.json b/content/docs/graph/concepts/meta.json index 38f6a49..a160e3e 100644 --- a/content/docs/graph/concepts/meta.json +++ b/content/docs/graph/concepts/meta.json @@ -4,11 +4,11 @@ "description": "Core concepts and fundamental understanding of Konnektr Graph", "pages": [ "dtdl", + "mcp-server", "querying", "validation", "event-routing", "telemetry", - "components", - "mcp-server" + "components" ] } \ No newline at end of file diff --git a/content/docs/graph/how-to-guides/mcp-server-business-twin.mdx b/content/docs/graph/how-to-guides/mcp-server-business-twin.mdx index ea9858c..52a12cc 100644 --- a/content/docs/graph/how-to-guides/mcp-server-business-twin.mdx +++ b/content/docs/graph/how-to-guides/mcp-server-business-twin.mdx @@ -13,49 +13,45 @@ In this example, we will model a **Smart Equipment System**, tracking **Employee ## Prerequisites -* **Konnektr Graph Standard Instance**: The MCP server is available on "Standard" and higher tiers. -* **API Credentials**: You'll need a Client ID and Secret from the [Konnektr Control Plane](https://ktrlplane.konnektr.io). -* **An MCP Client**: Claude Desktop, Gemini, or any MCP-compliant application. +* A **Konnektr Graph** instance. The MCP server is available on "Standard" and higher tiers. +* An **MCP Client** (e.g., Claude CLI, Claude Desktop, Gemini) that supports OAuth 2.1 or the `npx` command-line tool. --- ## Part 1: Connecting to the Hosted MCP Server -Every Konnektr Graph resource has its own dedicated MCP endpoint. +Your Konnektr Graph instance is accessible via the shared, secure MCP endpoint. ### 1. Identify Your Endpoint -Your MCP server is hosted at: -`https://{resource-id}.mcp.graph.konnektr.io` +The MCP server is hosted at: +`https://mcp.graph.konnektr.io/mcp?resource_id={your-resource-id}` + +You must replace `{your-resource-id}` with the actual ID of your Konnektr Graph instance. ### 2. Configure Your Client -The Hosted MCP Server uses OAuth 2.1 authentication—the same credentials you use for the Konnektr API. +The MCP Server uses **OAuth 2.1 with Dynamic Client Registration**. You don't need to provide a `client_id` or `client_secret`. Your client will guide you through a one-time browser login to authorize access. + +**For Claude CLI:** + +```bash +claude mcp add konnektr-graph --transport http https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id +``` + +**For Claude Desktop (and similar clients):** -Add this to your `claude_desktop_config.json` (or equivalent client config): +Edit your `claude_desktop_config.json` (or equivalent) with this simplified configuration: ```json { "mcpServers": { "konnektr": { - "url": "https://your-resource-id.mcp.graph.konnektr.io", - "transport": { - "type": "sse" - }, - "auth": { - "type": "oauth2", - "token_url": "https://auth.konnektr.io/oauth/token", - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "audience": "https://graph.konnektr.io", - "scope": "mcp:tools" - } + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id"] } } } ``` -> [!TIP] -> **Try the Demo:** You can test the platform using our public demo instance at `demo.mcp.graph.konnektr.io` which requires no authentication. - --- ## Part 2: Prompt Engineering for Twins @@ -97,9 +93,8 @@ The LLM can also perform complex analysis by writing Cypher queries. However, it ### The Query Workflow -1. **Understand the Schema:** The LLM should first understand the structure of the graph by calling `get_model`. -2. **Get the Query Rules:** The LLM should call `get_prompt(name: "GenerateQueryPrompt")`. This provides the rules for optimized Cypher on the AgeDigitalTwins platform (e.g., using `:Twin` labels and handling DTDL inheritance). -3. **Execute:** The LLM then writes and runs the query using `query_digital_twins`. +1. **Understand the Schema:** The LLM should first understand the structure of the graph by calling `list_models`. +3. **Execute:** The LLM then writes and runs the query using `query_digital_twins` (the documentation for the tool includes the query rules). **User Prompt:** > "Who in the R&D department is holding high-performance computing assets? Search for assets mentioning 'DGX' or 'Computing'."