diff --git a/_build_scripts/link-validator.js b/_build_scripts/link-validator.js index 99bf4ccaa..7d079b2b3 100644 --- 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 index 9847e5bc9..65ab440b9 100644 --- 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';
- {CodeExamples} +{CodeExamples}

@@ -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'; diff --git a/docs/weaviate/index.mdx b/docs/weaviate/index.mdx index 4c8c61433..16b030c07 100644 --- a/docs/weaviate/index.mdx +++ b/docs/weaviate/index.mdx @@ -64,6 +64,31 @@ return ;
})()} +## 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", + }, +]; + + + +
+ ## 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 new file mode 100644 index 000000000..f5f6f4dea --- /dev/null +++ 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. + + + +Add the following to your `.cursor/mcp.json` file: + +```json +{ + "mcpServers": { + "weaviate-docs": { + "type": "http", + "url": "https://weaviate-docs.mcp.kapa.ai" + } + } +} +``` + + + +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" + } + } +} +``` + + + +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). + + + +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). + + + +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). + + + +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" + } + } +} +``` + + + + +## 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 + +
+ Server not showing up + +- 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 + +
+ +
+ Connection errors + +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 + ``` + +
+ +
+ No results returned + +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) + +
+ +
+ Rate limiting + +The public Weaviate MCP server may have rate limits. If you experience issues: + +- Wait a few minutes before trying again + +
+ +## 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"; + + diff --git a/sidebars.js b/sidebars.js index eb96c4af5..61d797d2e 100644 --- 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: "
", }, { 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 index a1b99a482..6383409a9 100644 --- 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) {