diff --git a/docs/weaviate/best-practices/code-generation.md b/docs/weaviate/best-practices/code-generation.md index 9847e5bc9..e5a36d6ff 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,13 @@ 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: + +- [Connect with Claude Desktop](../mcp/docs-mcp-server.mdx#claude-desktop) +- [Connect with Cursor](../mcp/docs-mcp-server.mdx#cursor) + ### 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 +39,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 +110,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 4ea7d0c99..f30e227b7 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..0d4d6e1bf --- /dev/null +++ b/docs/weaviate/mcp/docs-mcp-server.mdx @@ -0,0 +1,229 @@ +--- +title: Weaviate Docs MCP Server +sidebar_label: Docs MCP Server +# tags: ["mcp"] +--- + +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 Docs MCP Server + +Here you can find instructions on how to connect to the Docs MCP Server from Claude Desktop and Cursor. For other platforms, consult their respective documentation (for example, [ChatGPT](https://platform.openai.com/docs/mcp), [Claude Code](https://code.claude.com/docs/en/mcp)). + +### Claude Desktop + +1. Locate your Claude Desktop configuration file, usually located here: + + - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + - **Linux**: `~/.config/Claude/claude_desktop_config.json` + +2. Add the Weaviate MCP server configuration: + +```json +{ + "mcpServers": { + "weaviate-docs": { + "url": "https://weaviate-docs-mcp.netlify.app/mcp-server" + } + } +} +``` + +3. Restart Claude Desktop. + +4. Look for the **Weaviate Docs** option under the _Search and tools_ section in Claude Desktop to confirm the server is connected. + +### Cursor + +1. Open Cursor settings (Cmd/Ctrl + ,). + +2. Navigate to **Features** → **Model Context Protocol**, + +3. Add the server URL: + +``` +https://weaviate-docs-mcp.netlify.app/mcp-server +``` + +4. Restart Cursor. + +## Using the MCP Server + +### In Claude Desktop + +Once configured, you can interact with Weaviate documentation naturally: + +**Example queries:** + +``` +"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?" +``` + +Claude will automatically use the MCP server to search the documentation and provide cited answers. + +### In Cursor + +While coding, you can ask Cursor to reference Weaviate documentation. Here's a typical workflow using the MCP server: + +1. **You're coding a Weaviate integration in Cursor** + + ```python + import weaviate + + # How do I set up authentication? + ``` + +2. **Ask Cursor**: "Search Weaviate docs for authentication setup with Python client". + +3. **MCP Server queries kapa.ai**, which searches the Weaviate documentation using semantic search. + +4. **You receive** a detailed answer with code examples and links to relevant docs. + +## Technical details + +### API endpoint + +The server exposes a single endpoint: + +``` +GET /mcp-server - SSE connection for MCP protocol +POST /mcp-server - MCP JSON-RPC requests +``` + +### Available tools + +The server provides one tool to AI assistants: + +**`search_weaviate_docs`** + +- **Description**: Search Weaviate documentation, tutorials, API references, and community content +- **Input**: `query` (string) - Your question or search query +- **Output**: Answers with citations and source links + +### Protocol support + +- **MCP Version**: 2024-11-05 +- **Protocol**: JSON-RPC 2.0 +- **Transport**: Server-Sent Events (SSE) + +## Troubleshooting + +
+ Server not showing up + +**Claude Desktop:** + +- Verify the config file syntax is valid JSON +- Check that the file path is correct for your OS +- Restart Claude Desktop completely (quit and reopen) + +**Cursor:** + +- Ensure the URL is entered correctly with `/mcp-server` path +- Check Cursor's MCP settings are enabled +- Restart Cursor + +
+ +
+ Connection errors + +If you see connection errors: + +1. Verify the server URL is accessible: + + ```bash + curl https://weaviate-docs-mcp.netlify.app/mcp-server + ``` + +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 +- Consider deploying your own instance for higher usage + +
+ +## FAQ + +
+ Is this official Weaviate infrastructure? + +Yes, the public Weaviate Docs MCP server is maintained by the Weaviate team for community use. + +
+ +
+ Does this work with other AI assistants? + +The MCP protocol is supported by various AI tools. While this guide focuses on Claude Desktop and Cursor, any MCP-compatible client should work. + +
+ +
+ Can I use this for my own documentation? + +Absolutely! The code is open source. Deploy your own instance with your kapa.ai credentials to create an MCP server for any documentation. + +
+ +
+ What's the rate limit? + +The public server has reasonable rate limits for community use. For high-volume usage, consider deploying your own instance. + +
+ +
+ Does this replace the Weaviate documentation site? + +No, this complements the documentation by bringing it into your development workflow. The full documentation site remains the authoritative source with complete content, guides, and resources. + +
+ +## 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 1174abea5..feb2d7a16 100644 --- a/sidebars.js +++ b/sidebars.js @@ -95,14 +95,16 @@ const sidebars = { }, items: [] }, + { + type: "html", + value: "
", + }, { type: "category", - label: "AI-based code generation", - link: { - type: "doc", - id: "weaviate/best-practices/code-generation", - }, - items: [] + label: "AI-assisted coding", + collapsed: false, + collapsible: false, + items: ["weaviate/mcp/docs-mcp-server", "weaviate/best-practices/code-generation"], } ], modelProvidersSidebar: [ diff --git a/tools/DOCS_MCP_SERVER.md b/tools/DOCS_MCP_SERVER.md new file mode 100644 index 000000000..795eb80bd --- /dev/null +++ b/tools/DOCS_MCP_SERVER.md @@ -0,0 +1,50 @@ +# Weaviate Docs MCP Server + +## How it works + +1. You ask a question in Claude Desktop or Cursor +2. The MCP server sends your query to kapa.ai +3. kapa.ai performs semantic search using Weaviate +4. Results are returned with citations and relevant documentation snippets + +### Architecture + +The MCP server is built as a Netlify Edge Function using Deno runtime. It implements the Model Context Protocol specification to expose Weaviate documentation as a tool that AI assistants can use. + +**Key components:** + +- **Edge Function**: Serverless function handling MCP protocol requests +- **kapa.ai Integration**: API integration for documentation search +- **Server-Sent Events (SSE)**: Real-time communication with MCP clients + +## How to deploy Weaviate Docs MCP server + +### Step 1: Get Your Kapa.ai Credentials + +1. Log in to your [kapa.ai dashboard](https://kapa.ai) +2. Navigate to **API Keys** and create a new API key +3. Note your **Project ID** (UUID in the dashboard URL) +4. Create a new **Integration** and note the Integration ID + +### Step 2: Install Netlify CLI + +```bash +npm install -g netlify-cli +netlify login +``` + +### Step 3: Configure Environment Variables + +```bash +netlify env:set KAPA_API_KEY "your-api-key" +netlify env:set KAPA_PROJECT_ID "your-project-id" +netlify env:set KAPA_INTEGRATION_ID "your-integration-id" +``` + +### Step 4: Deploy + +```bash +netlify deploy --prod +``` + +Your MCP server will be available at: `https://your-site-name.netlify.app/mcp-server`