Query your application with GraphRAG

Overview

GraphRAG builds a semantic knowledge base from the functional documents and source-code context available for a CAST Imaging application. It creates semantic representations of that content, extracts business concepts and their relationships, and can group related concepts into topics. The resulting knowledge graph is stored in the application’s Neo4j database.

You can then ask conceptual and business-oriented questions through an MCP-aware client such as GitHub Copilot, Claude Desktop or Codex App. The CAST Imaging MCP Server searches the generated knowledge graph and combines those semantic results with CAST Imaging’s structural information.

GraphRAG can also extract the business rules that the application implements and consolidate them into the same knowledge graph. Whether it does so is determined by the run scope you choose before the pipeline starts - see Run scope.

The GraphRAG generation service is included and enabled by default in CAST Imaging.

Compatibility

Querying GraphRAG requires the CAST Imaging MCP Server 3.1. GraphRAG is not supported by MCP Server 3.0.x or earlier releases.

Both GraphRAG and MCP Server 3.1 are under active development, and each 3.1.0-x release adds to the semantic search capabilities available to your MCP client. CAST therefore recommends that you install the latest 3.1.0-x release rather than pinning to a specific one, and that you keep CAST Imaging itself up to date.

What GraphRAG uses

GraphRAG uses the active documents associated with the application, including:

• AI-generated summaries for Transactions and Data Call Graphs.
• Functional-purpose documents for the objects present in those views.
• Business-rule-purpose documents for those objects, where the run scope includes business rules.
• Source code associated with those object-purpose documents.
• User-created post-its attached to objects, Transactions and Data Call Graphs.

Functional-purpose text and source code are represented separately. This helps GraphRAG preserve the business meaning of an object while still making relevant implementation details and code snippets discoverable.

GraphRAG uses only the current active version of an object and its documents. When an application is updated and the pipeline is run again, changed and new content is processed while unchanged content can be reused. Content that is no longer current is excluded from semantic search.

How it works

Generation

Before running GraphRAG, generate the AI summaries for the application’s Transactions and Data Call Graphs, from the GraphRAG page in CAST Imaging. These summaries also prepare the functional-purpose and source-code documents used for the objects in those views. See Prepare AI summaries.

Once that is done, choose the run scope and run the GraphRAG pipeline from the GraphRAG page. The pipeline:

1. Creates semantic representations of the active application documents and source-code context.
2. Extracts business entities and relationships.
3. Optionally groups related entities into topics.
4. Extracts and consolidates the application’s business rules, where the run scope includes them.

The generated data is stored in the application’s Neo4j database.

Retrieval

After the pipeline completes, an MCP-aware client queries the knowledge graph through the CAST Imaging MCP Server. Use semantic search for questions such as:

• What business processes are implemented in this application?
• Where is order cancellation handled?
• Which objects contribute to invoice validation?
• What concepts are related to customer onboarding?
• Show the functional context and relevant code for refund processing.
• Which business topics appear in this Transaction or Data Call Graph?
• Which business rules govern discount eligibility?

Use CAST Imaging’s structural search for exact questions about application inventories, objects, Transactions, call chains, dependencies, technologies and quality insights.

An MCP client can use both types of search in the same conversation. For example, it can first find a business concept semantically and then use structural information to trace its callers, callees or containing Transaction.

Before you start

Make sure that:

• CAST Imaging and the target application are installed and accessible.
• The application analysis is complete and its data source is configured.
• AI summaries have been generated for the application’s Transactions and Data Call Graphs.
• The GraphRAG service is running and reachable from CAST Imaging.
• Neo4j is reachable from both the GraphRAG service and the CAST Imaging MCP Server.
• The LLM and embedding settings are configured in AI Settings.
• The latest CAST Imaging MCP Server 3.1.0-x release is installed if you want to query GraphRAG from an MCP client.

Configure the LLM and embedding providers

Both are configured in AI Settings by a user with the Administrator role:

• LLM provider - used for completion when the pipeline runs.
• Embedding provider and model - used to create the semantic representations of your application documents and source code.

The embedding provider may be the same as, or different from, the LLM provider. For example, you can use Claude AI for generation and OpenAI for embeddings.

Where both use the same provider, CAST Imaging can reuse the stored LLM credentials, although the embedding model name is still required. Where they use different providers, configure separate embedding credentials.

The supported embedding providers, their credential requirements and their default models are listed in AI Settings - GraphRAG.

Prepare AI summaries

Before running GraphRAG:

1. Open the target application in CAST Imaging.
2. Generate the AI summaries for its Transactions and Data Call Graphs from the GraphRAG page - see Generate AI Summary for details about generating summaries, including in bulk. Note that you can also generate these summaries via the GraphRAG tab, described below.
3. Wait for AI-summary processing to complete.
4. Open the GraphRAG tab.

This preparation provides GraphRAG with:

• Functional summaries for Transactions and Data Call Graphs.
• The purpose of the objects participating in those views.
• The source-code context associated with those object-purpose documents.

User-created post-its remain additional context. They do not replace the primary object-purpose document.

Run GraphRAG from the UI

From the landing page select Customize the results for your chosen application:

Then choose the GraphRAG tab:

The configured AI provider and embedding model are displayed at the top of the page for quick reference, together with a Change link back to AI Settings:

The Beta info banner at the top of the page links directly to this documentation.

1. Confirm that the LLM and embedding settings are configured.
2. Choose the Run scope for the application - see Run scope.
   Available in ≥ 3.6.7-funcrel
3. Generate the AI summaries for the application’s Transactions and Data Call Graphs if not already complete.
4. Once that is complete, choose whether to run the Entity clustering stage (enabled by default):

5. Click Run Pipeline.

6. Wait until the job status shows complete.

The GraphRAG tab verifies that the service is available, that the required LLM and embedding settings are configured, and that the application data source is available. It may also prevent the pipeline from starting until the required application preparation is complete.

Run scope

The Run scope option at the top of the Build knowledge graph page determines how much of the application’s behavior the knowledge graph describes. Choose it first: both the content prepared in Prepare content and the stages listed in Choose pipeline stages follow from it.

Both scopes require the AI summaries to be generated before the pipeline runs.

Estimated cost

The AI Summaries section displays an estimated cost for generating the summaries for the objects you have selected, so that you can gauge the spend with your AI provider before starting the run:

The figure is a US dollar range - see Cost estimation for how it is calculated and what it excludes.

Summary run history

The Summary Run History section lists each AI summary generation run for the application:

The section is labelled Recent summary jobs and is now collapsible, collapsed by default, so that the configuration options remain the focus of the page.

Entity clustering

Keep Entity clustering enabled when you want GraphRAG to organize related concepts into readable topics and themes.

Clustering is optional. Only embedding generation is always run. Because clustering is an additional AI driven stage, it adds to the cost of the run - use the estimate shown on the stage to decide whether to include it.

Business rule extraction

Business rule extraction is an additional pipeline stage that identifies the business rules implemented by the application, then consolidates and organizes them into the knowledge graph. The stage works from the Business rule purpose content produced with the AI summaries, therefore those summaries must be regenerated before the stage can run.

Both the content item and the stage are marked Derived: you do not select either of them directly, they follow from the run scope. The Business rule extraction stage is always listed under Choose pipeline stages and shows the status Pending until a run scope that includes business rules is selected.

To run the stage:

1. Select Functional context + Business rules as the run scope. Business rule purpose is then added to Prepare content, noted as Included in the run scope above. It is generated for the same eligible objects as the AI summaries, using the existing checksum versioning.

2. Click Generate summaries so that the Business rule purpose content is produced.
3. Once the content is complete, run the GraphRAG pipeline.

Because this is an additional AI driven stage, both the extra summary content and the stage itself add to the cost of the run - see Cost estimation.

Pipeline stages

Each stage displays an estimated cost range before you start the run, so that you can see what the selected stages are likely to cost with your AI provider:

See Cost estimation for how each stage figure is calculated.

Cost estimation

Before a run starts, the GraphRAG tab shows an estimated cost as a US dollar range, both for the AI summaries and for each pipeline stage. Two things are worth knowing about these figures:

• They are produced from application metadata. Calculating an estimate does not call an AI model and does not consume billable tokens.
• Each estimate distinguishes the cost of the next run, which excludes work that is already current and can be reused, from the cost of processing everything from scratch.

The estimates account for the additional Business rule purpose content where the run scope includes business rules. An Estimated cost is shown against each content item and each pipeline stage, and an Estimated total is shown for Prepare content and for Choose pipeline stages.

Estimated tokens are converted to US dollars using the rates of the model that will do the work - the completion model for generation stages, the embedding model for embeddings - as configured in AI Settings:

cost = (input tokens × input rate + output tokens × output rate) / 1,000,000

AI summary estimates

The estimate covers the Transaction and Data Call Graph summaries, and is calculated in two parts:

• Object-purpose analysis - each distinct code object is estimated from its lines of code, the prompt and the expected output. An object whose purpose document is already current is excluded from the next-run estimate, and work shared between objects is deduplicated where possible.
• View summarization - each selected view is estimated from its objects, relationships, prompt chunks, expected summary and final aggregation. Where a reasoning model is used, the reasoning output you are billed for is included.

Recorded usage from the same application is used wherever it is available. Where it is not, the estimate is derived from a sample of the source, from comparable history for other applications, or from the size of the content to process.

Pipeline estimates

The pipeline estimate is the sum of the stages that will run:

Blank and very short text is excluded. Large source documents are split into chunks and can therefore produce several embedding calls.

On an application that has not been processed before, the extraction and clustering figures are projected from the counts of the stages that precede them, and are correspondingly less precise. Once content has been processed, later estimates count the data actually awaiting processing.

Monitor a run

The GraphRAG tab shows the current application status and stage progress. It also provides:

• The current stage and the work completed.
• Run history - see Run history below.
• Overall and stage-level AI token consumption.
• Cancellation for a running job.
• Downloadable logs for a selected run.

Logs can be downloaded while a run is active, but the log for the current stage may be incomplete until that stage finishes.

If a stage completes with failures or warnings, review the logs before relying on the generated results. A retry can continue recoverable work without rebuilding content that is already current.

Run history

The Run History section lists the pipeline runs executed for the application:

In addition to the date, duration, stages and status of each run, the following execution details are provided:

• Input and output tokens consumed.
• The primary AI provider and model used.
• The embedding provider and embedding model used.

Recording the provider and model alongside each run makes it easy to see which configuration produced the knowledge graph currently stored for the application - useful when the embedding configuration has been changed and the graph needs to be rebuilt.

Rerun after an application update

The GraphRAG pipeline is designed to be rerun safely:

• If nothing relevant has changed, completed work is reused and the run can finish quickly.
• If the application contains new or changed objects and documents, GraphRAG processes the new content and refreshes the affected semantic data.
• If a document was edited or removed, its previous semantic representation is no longer returned as current.
• User-created post-its are processed as independent documents and are refreshed when their content changes.

Refresh the application’s AI summaries before rerunning GraphRAG, so that Transaction, Data Call Graph and object-purpose documents represent the current application analysis.

GraphRAG service configuration

The provider, credentials, completion model and embedding model used for generation all come from AI Settings. The following GraphRAG-specific option is available to administrators:

#IMAGING-GRAPH-RAG
GRAPHRAG_PORT=8286

• GRAPHRAG_PORT controls the internal GraphRAG service port.

You can find this option here:

• For CAST Imaging installed on Docker/Podman, in the imaging-viewer .env file located in /opt/cast/installation/imaging-viewer/.env

• For CAST Imaging installed on Microsoft Windows, in the following file: %PROGRAMDATA%\CAST\Imaging\CAST-Imaging-Viewer\setup-config\imaginggraphrag\app.config

The pipeline selects its content from the active application documents, therefore no content-selection setting is required.

Query GraphRAG through the MCP Server

Semantic search over the GraphRAG knowledge graph is exposed by CAST Imaging MCP Server 3.1 - see CAST Imaging MCP Server 3.1 (beta).

Install the latest MCP Server 3.1.0-x release and enable the semantic search MCP server in its configuration (.env on Linux via Docker, configuration.conf on Microsoft Windows). The recommended configuration is:

SEMANTIC_MCP_ENABLED=true
SEMANTIC_MCP_TOOL_SURFACE_PROFILE=intents
NEO4J_URL=bolt://<neo4j-host>:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=<password>

See MCP Server 3.1 installation on Linux via Docker or MCP Server 3.1 installation on Microsoft Windows for the location of these options and for the other settings available.

For normal tenant-based operation, the MCP Server reads the embedding provider, model and credentials configured in CAST Imaging AI Settings.

MCP intents mode

intents is the default and recommended MCP tool-surface profile. It gives the AI client a compact search interface instead of exposing every GraphRAG function as a separate top-level tool. See Meta Tool mode for a full explanation, and for the full profile which remains available where you deliberately want every underlying function exposed directly.

With GraphRAG enabled, the MCP client receives four search tools:

• get_structural_search_function_syntax
• run_structural_search_function
• get_semantic_search_function_syntax
• run_semantic_search_function

The client uses the semantic syntax and execution tools to select the appropriate GraphRAG capability. You normally ask questions in natural language and do not need to select these functions manually.

Semantic-search capabilities include:

• Finding code and document context related to a business question.
• Finding extracted business entities by keyword.
• Listing entity types and relationship types.
• Listing or semantically searching entity topics.
• Finding prevalent concepts for an object, Transaction or Data Call Graph.
• Retrieving documents associated with a selected CAST Imaging identifier.
• Checking the GraphRAG configuration and connectivity.
• Adding supplied documentation to the semantic document store when requested.

Recommended setup flow

1. Configure a supported LLM provider in AI Settings.
2. Configure the embedding provider and model in AI Settings.
3. Ensure that the GraphRAG service and the application data source are available.
4. Choose the run scope for the application.
5. Generate or refresh the Transaction and Data Call Graph AI summaries where the application contains those views.
6. Run the GraphRAG pipeline from the application’s GraphRAG tab.
7. Install and configure the latest CAST Imaging MCP Server 3.1.0-x release, setting SEMANTIC_MCP_ENABLED=true and SEMANTIC_MCP_TOOL_SURFACE_PROFILE=intents.
8. Ask your MCP client to verify GraphRAG connectivity and the embedding configuration.
9. Ask semantic or business-oriented questions about the application.

Troubleshooting

Security consideration

The generated knowledge graph can contain functional documentation, user post-its and source-code-derived context, and semantic search may return relevant code snippets when they answer a question. Protect access to Neo4j, the GraphRAG service and the MCP Server according to your organization’s source-code access policy.

Key rules

• Configure the LLM and embedding settings in AI Settings before running GraphRAG.
• Generate or refresh the Transaction and Data Call Graph AI summaries before running GraphRAG.
• Check the estimated cost shown for the AI summaries and for each pipeline stage before starting a run.
• After changing the embedding provider or model, rerun GraphRAG before using semantic search.
• Choose the run scope before generating the AI summaries - Functional context + Business rules also generates the Business rule purpose content that the extraction stage needs.
• Use Entity clustering where business topics and themes are useful.
• Use semantic search for business meaning and relevant implementation context.
• Use structural search for exact CAST Imaging objects, dependencies, call paths, Transactions and quality information.
• Rerun GraphRAG after refreshing the AI summaries when the application analysis changes.