Skip to content

Commit b4e551f

Browse files
shiva-intugleshiva-intugle
authored
Merge pull request #65 from Intugle/features/docs-mcp-v2
features/docs mcp v2
2 parents 71af8b5 + 951c037 commit b4e551f

23 files changed

+474
-113
lines changed

‎docscontent/quickstart_content.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ type: markdown
3535
---
3636
## 1. LLM Configuration
3737

38-
Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For the semantic search feature, you will also need to set up Qdrant and provide an OpenAI API key. For detailed setup instructions, please refer to the [README.md](README.md) file.
38+
Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For the semantic search feature, you will also need to set up Qdrant and provide an OpenAI API key. For detailed setup instructions, please refer to the [README.md](https://github.com/Intugle/data-tools/blob/main/README.md) file.
3939

4040
You can configure the necessary services by setting the following environment variables:
4141

@@ -196,7 +196,7 @@ type: markdown
196196

197197
The semantic search feature allows you to search for columns in your datasets using natural language.
198198

199-
> **Note:** To use this feature, you need to have a running Qdrant instance and an OpenAI API key. Please refer to the [README.md](README.md) for detailed setup instructions.
199+
> **Note:** To use this feature, you need to have a running Qdrant instance and an OpenAI API key. Please refer to the [README.md](https://github.com/Intugle/data-tools/blob/main/README.md) for detailed setup instructions.
200200
>
201201
> **Google Colab Users:** If you are running this notebook in Google Colab, you may not be able to connect to a local Qdrant instance running in Docker. In this case, you will need to use a remotely hosted Qdrant server.
202202
>

‎docsite/docs/mcp-server.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
sidebar_position: 6
3+
title: MCP Server
4+
---
5+
6+
# Intugle MCP Server
7+
8+
The Intugle library includes a built-in MCP (Model Context Protocol) server that exposes your data environment as a set of tools that can be understood and used by AI assistants and LLM-powered clients.
9+
10+
By serving your project's context through this standardized protocol, you enable powerful conversational workflows, such as [Vibe Coding](./vibe-coding.md), and allow AI agents to interact with your data securely.
11+
12+
## 1. Setting up the MCP Server
13+
14+
Once you have built your semantic layer using the `SemanticModel`, you can easily expose it as a set of tools for an AI assistant by starting the built-in MCP server.
15+
16+
### Starting the Server
17+
18+
To start the server, run the following command in your terminal from your project's root directory:
19+
20+
```bash
21+
intugle-mcp
22+
```
23+
24+
This will start a server on `localhost:8080` by default. You should see output indicating that the server is running and that the `semantic_layer` service is mounted.
25+
26+
### Connecting from an MCP Client
27+
28+
With the server running, you can connect to it from any MCP-compatible client. The endpoint for the semantic layer is:
29+
30+
`http://localhost:8080/semantic_layer/mcp`
31+
32+
Popular clients that support MCP include AI-powered IDEs and standalone applications. Here’s how to configure a few of them:
33+
34+
- **Cursor**: [Configuring MCP Servers](https://docs.cursor.com/en/context/mcp#configuring-mcp-servers)
35+
- **Claude Code**: [Using MCP with Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)
36+
- **Claude Desktop**: [User Quickstart](https://modelcontextprotocol.info/docs/quickstart/user/)
37+
- **Gemini CLI**: [Configure MCP Servers](https://cloud.google.com/gemini/docs/codeassist/use-agentic-chat-pair-programmer#configure-mcp-servers)
38+
39+
## 2. Data Discovery Tools
40+
41+
The MCP server provides tools that allow an LLM client to discover and understand the structure of your data. These tools are essential for providing the AI with the context it needs to answer questions and generate valid queries or specifications.
42+
43+
These tools are only available after a `SemanticModel` has been successfully generated and loaded.
44+
45+
### `get_tables`
46+
47+
This tool returns a list of all available tables in your semantic model, along with their descriptions. It's the primary way for an AI assistant to discover what data is available.
48+
49+
- **Description**: Get list of tables in database along with their technical description.
50+
- **Returns**: A list of objects, where each object contains the `table_name` and `table_description`.
51+
52+
### `get_schema`
53+
54+
This tool retrieves the schema for one or more specified tables, including column names, data types, and other metadata including links. This allows the AI to understand the specific attributes of each table before attempting to query it.
55+
56+
- **Description**: Given database table names, get the schemas of the tables.
57+
- **Parameters**: `table_names` (a list of strings).
58+
- **Returns**: A dictionary where keys are table names and values are their detailed schemas.

‎docsite/docs/vibe-coding.md‎

Lines changed: 44 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,13 @@
11
---
2-
sidebar_position: 6
2+
sidebar_position: 7
33
title: Vibe Coding
44
---
55

66
# Vibe Coding with the MCP Server
77

8-
"Vibe Coding" is an interactive, conversational approach to development where you use natural language to generate code or specifications. Intugle embraces this by allowing you to serve your semantic layer through an MCP (Model Context Protocol) server.
8+
"Vibe Coding" is an interactive, conversational approach to data intelligence. Intugle embraces this by allowing you to serve your project as an MCP (Model Context Protocol) server.
99

10-
This turns your data into a "self-describing" resource that an AI assistant can understand, allowing you to "vibe" with your data to create specifications without writing them by hand.
11-
12-
:::info In Progress
13-
Currently, Vibe Coding is available for generating **Data Product** specifications. We are actively working on extending this capability to other modules in the Intugle ecosystem. Stay tuned for more updates!
14-
:::
10+
This turns your entire data workflow into a "self-describing" resource that an AI assistant can understand and operate. It allows you to "vibe" with the intugle library—using natural language to build semantic models, perform searches, and create data products from scratch.
1511

1612
## 1. Setting up the MCP Server
1713

@@ -29,13 +25,13 @@ To start the server, run the following command in your terminal from your projec
2925
intugle-mcp
3026
```
3127

32-
This will start a server on `localhost:8000` by default. You should see output indicating that the server is running and that the `semantic_layer` and `adapter` services are mounted.
28+
This will start a server on `localhost:8080` by default. You should see output indicating that the server is running and that the `semantic_layer` service is mounted.
3329

3430
### Connecting from an MCP Client
3531

3632
With the server running, you can connect to it from any MCP-compatible client. The endpoint for the semantic layer is:
3733

38-
`http://localhost:8000/semantic_layer/mcp`
34+
`http://localhost:8080/semantic_layer/mcp`
3935

4036
Popular clients that support MCP include AI-powered IDEs and standalone applications. Here’s how to configure a few of them:
4137

@@ -44,56 +40,53 @@ Popular clients that support MCP include AI-powered IDEs and standalone applicat
4440
- **Claude Desktop**: [User Quickstart](https://modelcontextprotocol.info/docs/quickstart/user/)
4541
- **Gemini CLI**: [Configure MCP Servers](https://cloud.google.com/gemini/docs/codeassist/use-agentic-chat-pair-programmer#configure-mcp-servers)
4642

47-
## 2. Using Vibe Coding
43+
## 2. Vibe Coding
4844

49-
The MCP server exposes powerful prompts that are designed to take your natural language requests and convert them directly into valid specifications.
45+
The MCP server exposes the `intugle-vibe` prompt. This prompt equips an AI assistant with knowledge of the Intugle library and access to its core tools. You can use it to guide you through the entire data intelligence workflow using natural language.
5046

51-
### Example: Generating a Data Product
47+
In your MCP-compatible client, you can invoke the prompt and provide your request. In most clients, this is done by typing `/` followed by the prompt name.
5248

53-
Currently, you can use the `create-dp` prompt to generate a `product_spec` dictionary for a Data Product.
49+
### Example 1: Getting Started and Building a Semantic Model
5450

55-
In your MCP-compatible client, you can invoke the prompt and provide your request. In most clients, this is done by typing `/` followed by the prompt name.
51+
If you are unsure how to start, you can ask for guidance. You can also ask the assistant to perform actions like creating a semantic model.
5652

5753
```
58-
/create-dp show me the top 5 patients with the most claims
54+
/intugle-vibe How do I create a semantic model?
55+
```
56+
```
57+
/intugle-vibe Create a semantic model over my healthcare data.
5958
```
6059

61-
:::tip Client-Specific Commands
62-
The exact command to invoke a prompt (e.g., using `/` or another prefix) can vary between clients. Be sure to check the documentation for your specific tool.
63-
:::
60+
The assistant will read the relevant documentation and guide you through the process or execute the steps if possible.
61+
62+
### Example 2: Generating a Data Product Specification
63+
64+
Once you have a semantic model, you can ask the assistant to create a specification for a reusable data product.
65+
66+
```
67+
/intugle-vibe create a data product specification for the top 5 patients with the most claims
68+
```
69+
70+
The AI assistant, connected to your MCP server, will understand that you are requesting a `product_spec`. It will use the `get_tables` and `get_schema` tools to find the `patients` and `claims` tables, and generate the specification.
71+
72+
### Example 3: Performing a Semantic Search
6473

65-
The AI assistant, connected to your MCP server, will understand the request, use the `get_tables` and `get_schema` tools to find the `patients` and `claims` tables, and generate the following `product_spec`:
66-
67-
```json
68-
{
69-
"name": "top_5_patients_by_claims",
70-
"fields": [
71-
{
72-
"id": "patients.first",
73-
"name": "first_name"
74-
},
75-
{
76-
"id": "patients.last",
77-
"name": "last_name"
78-
},
79-
{
80-
"id": "claims.id",
81-
"name": "number_of_claims",
82-
"category": "measure",
83-
"measure_func": "count"
84-
}
85-
],
86-
"filter": {
87-
"sort_by": [
88-
{
89-
"id": "claims.id",
90-
"alias": "number_of_claims",
91-
"direction": "desc"
92-
}
93-
],
94-
"limit": 5
95-
}
96-
}
74+
You can also perform a semantic search on your data.
75+
76+
```
77+
/intugle-vibe use semantic search to find columns related to 'hospital visit reasons'
9778
```
9879

99-
This workflow allows you to stay in your creative flow, rapidly iterating on data product ideas by describing what you want in plain English.
80+
The assistant will code out the semantic search capabilities of your `SemanticModel` to find and return relevant columns from your datasets.
81+
82+
:::tip Agent Mode
83+
Most modern, AI-powered clients support an "agent mode" where the coding assistant can handle the entire workflow for you.
84+
85+
For example, you can directly ask for a final output, like a CSV file:
86+
87+
`/intugle-vibe create a CSV of the top 10 patients by claim count`
88+
89+
The agent will understand the end goal and perform all the necessary intermediate steps for you. It will realize it needs to build the semantic model, generate the data product specification, execute it, and finally provide you with the resulting CSV file—all without you needing to manage the code or the process.
90+
:::
91+
92+
This workflow accelerates your journey from raw data to insightful data products. Simply describe what you want in plain English and let the assistant handle the details, freeing you from the hassle of digging through documentation.

‎notebooks/quickstart_fmcg.ipynb‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -123,15 +123,15 @@
123123
},
124124
{
125125
"cell_type": "code",
126-
"execution_count": 2,
126+
"execution_count": null,
127127
"id": "f0ecc2ba",
128128
"metadata": {},
129129
"outputs": [],
130130
"source": [
131131
"def generate_config(table_name: str) -> str:\n",
132132
" \"\"\"Append the base URL to the table name.\"\"\"\n",
133133
" return {\n",
134-
" \"path\": f\"./sample_data/fmcg/{table_name}.csv\",\n",
134+
" \"path\": f\"https://github.com/Intugle/data-tools/tree/main/sample_data/fmcg/{table_name}.csv\",\n",
135135
" \"type\": \"csv\",\n",
136136
" }\n",
137137
"\n",
@@ -2528,7 +2528,7 @@
25282528
"\n",
25292529
"The semantic search feature allows you to search for columns in your datasets using natural language. \n",
25302530
"\n",
2531-
"> **Note:** To use this feature, you need to have a running Qdrant instance and an OpenAI API key. Please refer to the [README.md](README.md) for detailed setup instructions.\n",
2531+
"> **Note:** To use this feature, you need to have a running Qdrant instance and an OpenAI API key. Please refer to the [README.md](https://github.com/Intugle/data-tools/blob/main/README.md) for detailed setup instructions.\n",
25322532
">\n",
25332533
"> **Google Colab Users:** If you are running this notebook in Google Colab, you may not be able to connect to a local Qdrant instance running in Docker. In this case, you will need to use a remotely hosted Qdrant server.\n",
25342534
">\n",

‎notebooks/quickstart_fmcg_snowflake.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -193,7 +193,7 @@
193193
"source": [
194194
"## 1. LLM Configuration\n",
195195
"\n",
196-
"Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For detailed setup instructions, please refer to the [README.md](README.md) file.\n",
196+
"Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For detailed setup instructions, please refer to the [README.md](https://github.com/Intugle/data-tools/blob/main/README.md) file.\n",
197197
"\n",
198198
"You can configure the necessary services by setting the following environment variables:\n",
199199
"\n",

‎notebooks/quickstart_healthcare.ipynb‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,15 +124,15 @@
124124
},
125125
{
126126
"cell_type": "code",
127-
"execution_count": 5,
127+
"execution_count": null,
128128
"id": "76771eda",
129129
"metadata": {},
130130
"outputs": [],
131131
"source": [
132132
"def generate_config(table_name: str) -> str:\n",
133133
" \"\"\"Append the base URL to the table name.\"\"\"\n",
134134
" return {\n",
135-
" \"path\": f\"./sample_data/healthcare/{table_name}.csv\",\n",
135+
" \"path\": f\"https://github.com/Intugle/data-tools/tree/main/sample_data/healthcare/{table_name}.csv\",\n",
136136
" \"type\": \"csv\",\n",
137137
" }\n",
138138
"\n",

‎notebooks/quickstart_healthcare_databricks.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@
107107
"source": [
108108
"## 1. LLM Configuration\n",
109109
"\n",
110-
"Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For detailed setup instructions, please refer to the [README.md](README.md) file.\n",
110+
"Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For detailed setup instructions, please refer to the [README.md](https://github.com/Intugle/data-tools/blob/main/README.md) file.\n",
111111
"\n",
112112
"You can configure the necessary services by setting the following environment variables:\n",
113113
"\n",

‎notebooks/quickstart_native_databricks.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@
6161
"source": [
6262
"## 1. LLM Configuration\n",
6363
"\n",
64-
"Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For the semantic search feature, you will also need to set up Qdrant and provide an OpenAI API key. For detailed setup instructions, please refer to the [README.md](README.md) file.\n",
64+
"Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For the semantic search feature, you will also need to set up Qdrant and provide an OpenAI API key. For detailed setup instructions, please refer to the [README.md](https://github.com/Intugle/data-tools/blob/main/README.md) file.\n",
6565
"\n",
6666
"You can configure the necessary services by setting the following environment variables:\n",
6767
"\n",

‎notebooks/quickstart_native_snowflake.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@
110110
"source": [
111111
"## 1. LLM Configuration\n",
112112
"\n",
113-
"Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For the semantic search feature, you will also need to set up Qdrant and provide an OpenAI API key. For detailed setup instructions, please refer to the [README.md](README.md) file.\n",
113+
"Before running the project, you need to configure a Large Language Model (LLM). This is used for tasks like generating business glossaries and predicting links between tables. For the semantic search feature, you will also need to set up Qdrant and provide an OpenAI API key. For detailed setup instructions, please refer to the [README.md](https://github.com/Intugle/data-tools/blob/main/README.md) file.\n",
114114
"\n",
115115
"You can configure the necessary services by setting the following environment variables:\n",
116116
"\n",

‎notebooks/quickstart_sports_media.ipynb‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,15 +124,15 @@
124124
},
125125
{
126126
"cell_type": "code",
127-
"execution_count": 2,
127+
"execution_count": null,
128128
"id": "f7367816",
129129
"metadata": {},
130130
"outputs": [],
131131
"source": [
132132
"def generate_config(table_name: str) -> str:\n",
133133
" \"\"\"Append the base URL to the table name.\"\"\"\n",
134134
" return {\n",
135-
" \"path\": f\"./sample_data/sports_media/{table_name}.csv\",\n",
135+
" \"path\": f\"https://github.com/Intugle/data-tools/tree/main/sample_data/sports_media/{table_name}.csv\",\n",
136136
" \"type\": \"csv\",\n",
137137
" }\n",
138138
"\n",

0 commit comments

Comments
 (0)