Merge pull request #256 from weaviate/docs-mcp-server

g-despot · web-flow · commit e58eb638bf43 · 2026-01-15T14:08:58.000+01:00
[New docs] Add Weaviate Docs MCP guide
diff --git a/_build_scripts/link-validator.js b/_build_scripts/link-validator.js
@@ -47,6 +47,7 @@ const domainsToIgnore = [
     'https://towardsdatascience.com/',
     'https://voyageai.com/',
     'https://weaviateagents.featurebase.app',
+    'https://weaviate-docs.mcp.kapa.ai/',
     'https://youtu.be/',
     'https://www.youtube.com',
     'https://x.com',
diff --git a/docs/weaviate/best-practices/code-generation.md b/docs/weaviate/best-practices/code-generation.md
@@ -1,13 +1,11 @@
 ---
-title: AI-based Weaviate code generation
-sidebar_position: 50
+title: AI-assisted Weaviate code generation
+sidebar_label: Vibe coding - Best practices
 description: "Tips and techniques for using generative AI models to write better Weaviate-related code."
 image: og/docs/howto.jpg
 # tags: ['best practices', 'how-to']
 ---
 
-# AI-based Weaviate code generation (vibe-coding)
-
 Generative AI models are becoming more capable at writing code. This practice is often referred to as "vibe-coding" or "AI-assisted coding". While this can speed up development, it is also subject to some pitfalls, such as hallucinations due to out-of-date, or missing information in the training data.
 
 Here are some tips for writing Weaviate client library code with generative AI models and tooling, based on our anecdotal experience.
@@ -16,6 +14,10 @@ Here are some tips for writing Weaviate client library code with generative AI m
 
 ## Specific recommendations
 
+### Weaviate Docs MCP Server
+
+The **[Weaviate Docs MCP Server](../mcp/docs-mcp-server.mdx)** brings instant access to Weaviate's documentation directly into your AI development environment. Built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro), this server integrates seamlessly with tools like Claude Desktop and Cursor, allowing you to query Weaviate's documentation without leaving your IDE.
+
 ### High-performing models
 
 As of July 2025, we've seen these models perform well for code generation. (Assessed by the correctness of generated [Python v4 client library](/weaviate/client-libraries/python/index.mdx) code.)
@@ -34,12 +36,12 @@ We found that performances of the above LLMs improved significantly when provide
 
 As a starting point, we have curated a set of code examples below. Try copy and pasting this block of code into your prompt.
 
-import CodeExamples from '!!raw-loader!/_includes/code/python/best-practices.python.ai.py';
+import CodeExamples from '!!raw-loader!/\_includes/code/python/best-practices.python.ai.py';
 import CodeBlock from '@theme/CodeBlock';
 
 <div style={{height: '300px', overflow: 'auto'}}>
 
-  <CodeBlock language="python">{CodeExamples}</CodeBlock>
+<CodeBlock language="python">{CodeExamples}</CodeBlock>
 
 </div>
 <br/>
@@ -105,6 +107,6 @@ If you have any questions or feedback, please let us know by opening an issue on
 
 ## Questions and feedback
 
-import DocsFeedback from '/_includes/docs-feedback.mdx';
+import DocsFeedback from '/\_includes/docs-feedback.mdx';
 
 <DocsFeedback/>
diff --git a/docs/weaviate/index.mdx b/docs/weaviate/index.mdx
@@ -64,6 +64,31 @@ return <CardsSection items={regularItems} className={styles.smallCards} />;
 <br />
 })()}
 
+## AI-assisted coding
+
+Check out our resources on AI-assisted coding (_Vibe coding_) with Weaviate:
+
+export const vibeCodingCardsData = [
+  {
+    id: "new",
+    title: "Weaviate Docs MCP Server",
+    description: "Instant access to Weaviate's documentation directly in your AI development environment. ",
+    link: "/weaviate/mcp/docs-mcp-server",
+    icon: "fas fa-book",
+  },
+  {
+    id: "academy",
+    title: "Best practices for coding with AI",
+    description: "Avoid hallucinations and improve your AI-assisted coding experience.",
+    link: "/weaviate/best-practices/code-generation",
+    icon: "fas fa-lightbulb",
+  },
+];
+
+<CardsSection items={vibeCodingCardsData} className={styles.smallCards} />
+
+<br />
+
 ## What is Weaviate?
 
 Weaviate is an **open-source vector database** designed to store and index both data objects and their vector embeddings. This architecture enables advanced semantic search capabilities by comparing the meaning encoded in vectors rather than relying solely on keyword matching. Key capabilities include:
diff --git a/docs/weaviate/mcp/docs-mcp-server.mdx b/docs/weaviate/mcp/docs-mcp-server.mdx
@@ -0,0 +1,197 @@
+---
+title: Weaviate Docs MCP Server
+sidebar_label: Docs MCP Server
+# tags: ["mcp"]
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+The **Weaviate Docs MCP Server** brings instant access to Weaviate's documentation directly into your AI development environment. Built on the Model Context Protocol (MCP), this server integrates seamlessly with tools like Claude Desktop and Cursor, allowing you to query Weaviate's documentation without leaving your IDE.
+
+The MCP server uses [kapa.ai](https://kapa.ai) (which in turn uses Weaviate under the hood) as its knowledge engine, which powers the search and retrieval of Weaviate documentation. The server offers:
+
+- **Instant documentation access**: Search Weaviate docs without context switching.
+- **Multi-source knowledge base**: Queries across docs, tutorials, API references, GitHub issues and community content.
+- **Always up-to-date**: Automatically syncs with the latest Weaviate documentation.
+
+## How to setup MCP Server
+
+:::note MCP server URL
+
+**URL**: **https://weaviate-docs.mcp.kapa.ai**
+
+:::
+
+Setup steps vary depending on which AI assistant you're using.
+
+<Tabs groupId="platform">
+<TabItem value="cursor" label="Cursor">
+Add the following to your `.cursor/mcp.json` file:
+
+```json
+{
+  "mcpServers": {
+    "weaviate-docs": {
+      "type": "http",
+      "url": "https://weaviate-docs.mcp.kapa.ai"
+    }
+  }
+}
+```
+
+</TabItem>
+<TabItem value="vsc" label="VS Code">
+Prerequisites: VS Code 1.102+ with GitHub Copilot enabled.
+
+Create an `mcp.json` file in your workspace `.vscode` folder:
+
+```json
+{
+  "servers": {
+    "weaviate-docs": {
+      "type": "http",
+      "url": "https://weaviate-docs.mcp.kapa.ai"
+    }
+  }
+}
+```
+
+</TabItem>
+<TabItem value="claude_code" label="Claude Code">
+Run the following command in your terminal:
+```bash
+claude mcp add --transport http weaviate-docs https://weaviate-docs.mcp.kapa.ai
+```
+Then run the `/mcp` command in Claude Code and follow the steps in your browser to authenticate.
+
+For more information, see the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp).
+
+</TabItem>
+<TabItem value="chatgpt_desktop" label="ChatGPT Desktop">
+ChatGPT Desktop supports MCP servers in developer mode:
+
+1. Open ChatGPT Desktop.
+2. Go to **Settings** > **Apps** > **Advanced settings**.
+3. Enable **Developer mode**.
+4. Navigate to **Settings** > **Connectors**.
+5. Click **Create** and enter:
+
+- **Name**: Weaviate Docs
+- **URL**: https://weaviate-docs.mcp.kapa.ai
+
+For more information, see the [ChatGPT Desktop MCP documentation](https://platform.openai.com/docs/guides/developer-mode).
+
+  </TabItem>
+<TabItem value="claude_desktop" label="Claude Desktop">
+Claude Desktop supports MCP servers:
+
+1. Open Claude Desktop.
+2. Go to **Settings** > **Connectors**.
+3. Click **Add custom connector** and enter:
+
+- **Name**: Weaviate Docs
+- **URL**: https://weaviate-docs.mcp.kapa.ai
+
+4. Click on **Connect** and follow the steps in your browser to authenticate.
+
+Restart Claude Desktop for changes to take effect.
+
+For more details, see the [Claude Desktop documentation](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).
+
+</TabItem>
+<TabItem value="other" label="Other">
+MCP is an open protocol supported by many clients. Use the server URL https://weaviate-docs.mcp.kapa.ai and refer to your client's documentation for setup instructions.
+
+Most clients accept the standard MCP JSON configuration format:
+
+```json
+{
+  "mcpServers": {
+    "weaviate-docs": {
+      "url": "https://weaviate-docs.mcp.kapa.ai"
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+## Using the MCP Server
+
+Once configured, you can ask context-aware questions about Weaviate from within your editor. For example:
+
+```
+"How do I set up a hybrid search in Weaviate?"
+
+"What are the best practices for schema design in Weaviate?"
+
+"Search the Weaviate docs for information about BM25 algorithm"
+
+"What's the difference between vector and keyword search in Weaviate?"
+```
+
+## Troubleshooting
+
+<details>
+  <summary>Server not showing up</summary>
+
+- Check that the file path is correct for your OS
+- Restart the app completely
+- Ensure the URL is entered correctly
+- Verify the config file syntax is valid JSON
+
+</details>
+
+<details>
+  <summary>Connection errors</summary>
+
+If you see connection errors:
+
+1. Verify the server URL is accessible:
+
+   ```bash
+   curl https://weaviate-docs.mcp.kapa.ai
+   ```
+
+2. Check your internet connection
+
+3. Try the MCP Inspector to debug:
+   ```bash
+   npx @modelcontextprotocol/inspector
+   ```
+
+</details>
+
+<details>
+  <summary>No results returned</summary>
+
+If queries return empty results:
+
+- Check that your question is relevant to Weaviate documentation
+- Try rephrasing your query
+- Verify the MCP server is properly configured (test with curl)
+
+</details>
+
+<details>
+  <summary>Rate limiting</summary>
+
+The public Weaviate MCP server may have rate limits. If you experience issues:
+
+- Wait a few minutes before trying again
+
+</details>
+
+## Further resources
+
+- [Vibe coding - Best practices](../best-practices/code-generation.md)
+- [MCP documentation](https://modelcontextprotocol.io)
+- [kapa.ai documentation](https://docs.kapa.ai)
+
+## Questions and feedback
+
+import DocsFeedback from "/_includes/docs-feedback.mdx";
+
+<DocsFeedback />
diff --git a/sidebars.js b/sidebars.js
@@ -49,14 +49,6 @@ const sidebars = {
         },
       ],
     },
-    {
-      type: "link",
-      label: "Concepts & architecture",
-      href: "https://academy.weaviate.io/courses/wa050-py",
-      customProps: {
-        academyOnly: true,
-      },
-    },
     {
       type: "category",
       label: "Starter guides",
@@ -101,22 +93,35 @@ const sidebars = {
         type: "doc",
         id: "weaviate/best-practices/index",
       },
-      items: []
+      items: [],
     },
     {
       type: "category",
-      label: "AI-based code generation",
+      label: "AI-assisted (vibe) coding",
+      collapsed: true,
       link: {
         type: "doc",
         id: "weaviate/best-practices/code-generation",
       },
-      items: []
+      items: ["weaviate/mcp/docs-mcp-server"],
+    },
+    {
+      type: "html",
+      value: "<hr class='sidebar-divider' />",
     },
     {
       type: "link",
       label: "Integration ecosystem",
       href: "https://weaviate.io/product/integrations",
-    }
+    },
+    {
+      type: "link",
+      label: "Concepts & architecture",
+      href: "https://academy.weaviate.io/courses/wa050-py",
+      customProps: {
+        academyOnly: true,
+      },
+    },
   ],
   modelProvidersSidebar: [
     {
@@ -149,7 +154,7 @@ const sidebars = {
               },
               items: [
                 "weaviate/model-providers/weaviate/embeddings",
-                "weaviate/model-providers/weaviate/embeddings-multimodal"
+                "weaviate/model-providers/weaviate/embeddings-multimodal",
               ],
             },
             {
@@ -422,7 +427,9 @@ const sidebars = {
                 type: "doc",
                 id: "weaviate/model-providers/imagebind/index",
               },
-              items: ["weaviate/model-providers/imagebind/embeddings-multimodal"],
+              items: [
+                "weaviate/model-providers/imagebind/embeddings-multimodal",
+              ],
             },
             {
               type: "category",
@@ -772,9 +779,7 @@ const sidebars = {
             type: "doc",
             id: "weaviate/client-libraries/java/index",
           },
-          items: [
-            "weaviate/client-libraries/java/java-v5",
-          ],
+          items: ["weaviate/client-libraries/java/java-v5"],
         },
         {
           type: "doc",
diff --git a/src/theme/Root.js b/src/theme/Root.js
@@ -64,6 +64,9 @@ export default function Root({ children }) {
           "data-modal-footer",
           "Powered by Weaviate and kapa.ai"
         );
+        script.setAttribute("data-mcp-enabled", "true");
+        script.setAttribute("data-mcp-server-url", "weaviate.mcp.kapa.ai");
+        script.setAttribute("data-mcp-button-text", "Use Docs MCP");
         script.async = true;
         document.body.appendChild(script);
       } else if (!shouldLoadWidget && existingScript) {
