diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000..a123578 Binary files /dev/null and b/.DS_Store differ diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..b17149b --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +*.mdx \ No newline at end of file diff --git a/api-reference/client-api/connection-management.mdx b/api-reference/client-api/connection-management.mdx new file mode 100644 index 0000000..844f896 --- /dev/null +++ b/api-reference/client-api/connection-management.mdx @@ -0,0 +1,8 @@ +--- +title: "Connection Management" +description: "Manage MCP client connections" +--- + +# Connection Management + +Manage MCP client connections diff --git a/api-reference/client-api/resource-consumption.mdx b/api-reference/client-api/resource-consumption.mdx new file mode 100644 index 0000000..39388bf --- /dev/null +++ b/api-reference/client-api/resource-consumption.mdx @@ -0,0 +1,8 @@ +--- +title: "Resource Consumption" +description: "Work with MCP resources from clients" +--- + +# Resource Consumption + +Work with MCP resources from clients diff --git a/api-reference/client-api/tool-invocation.mdx b/api-reference/client-api/tool-invocation.mdx new file mode 100644 index 0000000..a76a659 --- /dev/null +++ b/api-reference/client-api/tool-invocation.mdx @@ -0,0 +1,8 @@ +--- +title: "Tool Invocation" +description: "Invoke MCP tools from clients" +--- + +# Tool Invocation + +Invoke MCP tools from clients diff --git a/api-reference/endpoint/create.mdx b/api-reference/endpoint/create.mdx deleted file mode 100644 index 5689f1b..0000000 --- a/api-reference/endpoint/create.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Create Plant' -openapi: 'POST /plants' ---- diff --git a/api-reference/endpoint/delete.mdx b/api-reference/endpoint/delete.mdx deleted file mode 100644 index 657dfc8..0000000 --- a/api-reference/endpoint/delete.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Delete Plant' -openapi: 'DELETE /plants/{id}' ---- diff --git a/api-reference/endpoint/get.mdx b/api-reference/endpoint/get.mdx deleted file mode 100644 index 56aa09e..0000000 --- a/api-reference/endpoint/get.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: 'Get Plants' -openapi: 'GET /plants' ---- diff --git a/api-reference/error-handling.mdx b/api-reference/error-handling.mdx new file mode 100644 index 0000000..b5932b7 --- /dev/null +++ b/api-reference/error-handling.mdx @@ -0,0 +1,8 @@ +--- +title: "Error Handling" +description: "Handle errors in MCP implementations" +--- + +# Error Handling + +Handle errors in MCP implementations diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx deleted file mode 100644 index c835b78..0000000 --- a/api-reference/introduction.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: 'Introduction' -description: 'Example section for showcasing API endpoints' ---- - - - If you're not looking to build API reference documentation, you can delete - this section by removing the api-reference folder. - - -## Welcome - -There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification. - - - View the OpenAPI specification file - - -## Authentication - -All API endpoints are authenticated using Bearer tokens and picked up from the specification file. - -```json -"security": [ - { - "bearerAuth": [] - } -] -``` diff --git a/api-reference/message-types.mdx b/api-reference/message-types.mdx new file mode 100644 index 0000000..fe9cff8 --- /dev/null +++ b/api-reference/message-types.mdx @@ -0,0 +1,8 @@ +--- +title: "Message Types" +description: "Complete reference of MCP message formats" +--- + +# Message Types + +Complete reference of MCP message formats diff --git a/api-reference/openapi.json b/api-reference/openapi.json deleted file mode 100644 index b1509be..0000000 --- a/api-reference/openapi.json +++ /dev/null @@ -1,195 +0,0 @@ -{ - "openapi": "3.0.1", - "info": { - "title": "OpenAPI Plant Store", - "description": "A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification", - "license": { - "name": "MIT" - }, - "version": "1.0.0" - }, - "servers": [ - { - "url": "http://sandbox.mintlify.com" - } - ], - "security": [ - { - "bearerAuth": [] - } - ], - "paths": { - "/plants": { - "get": { - "description": "Returns all plants from the system that the user has access to", - "parameters": [ - { - "name": "limit", - "in": "query", - "description": "The maximum number of results to return", - "schema": { - "type": "integer", - "format": "int32" - } - } - ], - "responses": { - "200": { - "description": "Plant response", - "content": { - "application/json": { - "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Plant" - } - } - } - } - }, - "400": { - "description": "Unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "post": { - "description": "Creates a new plant in the store", - "requestBody": { - "description": "Plant to add to the store", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NewPlant" - } - } - }, - "required": true - }, - "responses": { - "200": { - "description": "plant response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Plant" - } - } - } - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/plants/{id}": { - "delete": { - "description": "Deletes a single plant based on the ID supplied", - "parameters": [ - { - "name": "id", - "in": "path", - "description": "ID of plant to delete", - "required": true, - "schema": { - "type": "integer", - "format": "int64" - } - } - ], - "responses": { - "204": { - "description": "Plant deleted", - "content": {} - }, - "400": { - "description": "unexpected error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "Plant": { - "required": [ - "name" - ], - "type": "object", - "properties": { - "name": { - "description": "The name of the plant", - "type": "string" - }, - "tag": { - "description": "Tag to specify the type", - "type": "string" - } - } - }, - "NewPlant": { - "allOf": [ - { - "$ref": "#/components/schemas/Plant" - }, - { - "required": [ - "id" - ], - "type": "object", - "properties": { - "id": { - "description": "Identification number of the plant", - "type": "integer", - "format": "int64" - } - } - } - ] - }, - "Error": { - "required": [ - "error", - "message" - ], - "type": "object", - "properties": { - "error": { - "type": "integer", - "format": "int32" - }, - "message": { - "type": "string" - } - } - } - }, - "securitySchemes": { - "bearerAuth": { - "type": "http", - "scheme": "bearer" - } - } - } -} \ No newline at end of file diff --git a/api-reference/protocol-overview.mdx b/api-reference/protocol-overview.mdx new file mode 100644 index 0000000..b58d90a --- /dev/null +++ b/api-reference/protocol-overview.mdx @@ -0,0 +1,8 @@ +--- +title: "Protocol Overview" +description: "Understanding the Model Context Protocol" +--- + +# Protocol Overview + +Understanding the Model Context Protocol diff --git a/api-reference/python/class-reference.mdx b/api-reference/python/class-reference.mdx new file mode 100644 index 0000000..43739a4 --- /dev/null +++ b/api-reference/python/class-reference.mdx @@ -0,0 +1,8 @@ +--- +title: "Python Class Reference" +description: "Complete Python SDK class documentation" +--- + +# Python Class Reference + +Complete Python SDK class documentation diff --git a/api-reference/python/examples.mdx b/api-reference/python/examples.mdx new file mode 100644 index 0000000..94c751c --- /dev/null +++ b/api-reference/python/examples.mdx @@ -0,0 +1,8 @@ +--- +title: "Python Examples" +description: "Example Python implementations" +--- + +# Python Examples + +Example Python implementations diff --git a/api-reference/python/type-hints.mdx b/api-reference/python/type-hints.mdx new file mode 100644 index 0000000..d037e47 --- /dev/null +++ b/api-reference/python/type-hints.mdx @@ -0,0 +1,8 @@ +--- +title: "Python Type Hints" +description: "Python type system documentation" +--- + +# Python Type Hints + +Python type system documentation diff --git a/api-reference/server-api/event-handling.mdx b/api-reference/server-api/event-handling.mdx new file mode 100644 index 0000000..dab1bc3 --- /dev/null +++ b/api-reference/server-api/event-handling.mdx @@ -0,0 +1,8 @@ +--- +title: "Event Handling" +description: "Handle events in your MCP server" +--- + +# Event Handling + +Handle events in your MCP server diff --git a/api-reference/server-api/resource-management.mdx b/api-reference/server-api/resource-management.mdx new file mode 100644 index 0000000..34de1ab --- /dev/null +++ b/api-reference/server-api/resource-management.mdx @@ -0,0 +1,8 @@ +--- +title: "Resource Management" +description: "Manage resources in your MCP server" +--- + +# Resource Management + +Manage resources in your MCP server diff --git a/api-reference/server-api/tool-implementation.mdx b/api-reference/server-api/tool-implementation.mdx new file mode 100644 index 0000000..0ede2a0 --- /dev/null +++ b/api-reference/server-api/tool-implementation.mdx @@ -0,0 +1,8 @@ +--- +title: "Tool Implementation" +description: "Implement tools in your MCP server" +--- + +# Tool Implementation + +Implement tools in your MCP server diff --git a/api-reference/typescript/class-reference.mdx b/api-reference/typescript/class-reference.mdx new file mode 100644 index 0000000..c08a40d --- /dev/null +++ b/api-reference/typescript/class-reference.mdx @@ -0,0 +1,8 @@ +--- +title: "TypeScript Class Reference" +description: "Complete TypeScript SDK class documentation" +--- + +# TypeScript Class Reference + +Complete TypeScript SDK class documentation diff --git a/api-reference/typescript/examples.mdx b/api-reference/typescript/examples.mdx new file mode 100644 index 0000000..7b5b7b5 --- /dev/null +++ b/api-reference/typescript/examples.mdx @@ -0,0 +1,8 @@ +--- +title: "TypeScript Examples" +description: "Example TypeScript implementations" +--- + +# TypeScript Examples + +Example TypeScript implementations diff --git a/api-reference/typescript/type-definitions.mdx b/api-reference/typescript/type-definitions.mdx new file mode 100644 index 0000000..cebeb24 --- /dev/null +++ b/api-reference/typescript/type-definitions.mdx @@ -0,0 +1,8 @@ +--- +title: "TypeScript Type Definitions" +description: "TypeScript type system documentation" +--- + +# TypeScript Type Definitions + +TypeScript type system documentation diff --git a/create-docs.sh b/create-docs.sh new file mode 100644 index 0000000..03dda90 --- /dev/null +++ b/create-docs.sh @@ -0,0 +1,75 @@ +#!/bin/bash + +# Create base directories +mkdir -p docs/{guides,recipes,deployment,api,server-api,client-api,typescript,python} + +# Function to create an .mdx file with frontmatter +create_mdx() { + local filepath=$1 + local title=$2 + local description=$3 + + echo "Creating $filepath..." + cat > "$filepath" < - **Prerequisite**: Please install Node.js (version 19 or higher) before proceeding. - - -Follow these steps to install and run Mintlify on your operating system: - -**Step 1**: Install Mintlify: - - - - ```bash npm - npm i -g mintlify - ``` - -```bash yarn -yarn global add mintlify -``` - - - -**Step 2**: Navigate to the docs directory (where the `mint.json` file is located) and execute the following command: - -```bash -mintlify dev -``` - -A local preview of your documentation will be available at `http://localhost:3000`. - -### Custom Ports - -By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. To run Mintlify on port 3333, for instance, use this command: - -```bash -mintlify dev --port 3333 -``` - -If you attempt to run Mintlify on a port that's already in use, it will use the next available port: - -```md -Port 3000 is already in use. Trying 3001 instead. -``` - -## Mintlify Versions - -Please note that each CLI release is associated with a specific version of Mintlify. If your local website doesn't align with the production version, please update the CLI: - - - -```bash npm -npm i -g mintlify@latest -``` - -```bash yarn -yarn global upgrade mintlify -``` - - - -## Validating Links - -The CLI can assist with validating reference links made in your documentation. To identify any broken links, use the following command: - -```bash -mintlify broken-links -``` - -## Deployment - - - Unlimited editors available under the [Pro - Plan](https://mintlify.com/pricing) and above. - - -If the deployment is successful, you should see the following: - - - - - -## Code Formatting - -We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting. - -## Troubleshooting - - - - - This may be due to an outdated version of node. Try the following: - 1. Remove the currently-installed version of mintlify: `npm remove -g mintlify` - 2. Upgrade to Node v19 or higher. - 3. Reinstall mintlify: `npm install -g mintlify` - - - - - Solution: Go to the root of your device and delete the \~/.mintlify folder. Afterwards, run `mintlify dev` again. - - - -Curious about what changed in the CLI version? [Check out the CLI changelog.](https://www.npmjs.com/package/mintlify?activeTab=versions) diff --git a/docs/deployment/configuration.mdx b/docs/deployment/configuration.mdx new file mode 100644 index 0000000..91b7311 --- /dev/null +++ b/docs/deployment/configuration.mdx @@ -0,0 +1,5 @@ +--- +title: "Configuration" +description: "Configure MCP servers for production" +--- + diff --git a/docs/deployment/environment-setup.mdx b/docs/deployment/environment-setup.mdx new file mode 100644 index 0000000..102a91f --- /dev/null +++ b/docs/deployment/environment-setup.mdx @@ -0,0 +1,4 @@ +--- +title: "Environment Setup" +description: "Set up your production environment" +--- \ No newline at end of file diff --git a/docs/deployment/monitoring.mdx b/docs/deployment/monitoring.mdx new file mode 100644 index 0000000..72aa561 --- /dev/null +++ b/docs/deployment/monitoring.mdx @@ -0,0 +1,8 @@ +--- +title: "Monitoring" +description: "Monitor your MCP servers in production" +--- + +# Monitoring + +Monitor your MCP servers in production diff --git a/docs/development.mdx b/docs/development.mdx new file mode 100644 index 0000000..e69de29 diff --git a/docs/guides/first-mcp-server.mdx b/docs/guides/first-mcp-server.mdx new file mode 100644 index 0000000..f2df732 --- /dev/null +++ b/docs/guides/first-mcp-server.mdx @@ -0,0 +1,8 @@ +--- +title: "Your First MCP Server" +description: "Build a complete MCP server from scratch" +--- + +# Your First MCP Server + +Build a complete MCP server from scratch diff --git a/docs/guides/implementing-tools.mdx b/docs/guides/implementing-tools.mdx new file mode 100644 index 0000000..da25884 --- /dev/null +++ b/docs/guides/implementing-tools.mdx @@ -0,0 +1,8 @@ +--- +title: "Implementing Tools" +description: "Create tools that LLMs can invoke" +--- + +# Implementing Tools + +Create tools that LLMs can invoke diff --git a/docs/guides/integrating-with-llm.mdx b/docs/guides/integrating-with-llm.mdx new file mode 100644 index 0000000..a801e53 --- /dev/null +++ b/docs/guides/integrating-with-llm.mdx @@ -0,0 +1,385 @@ +--- +title: "Integrating MCP into Your LLM Application" +description: 'Learn how to integrate the Model Context Protocol (MCP) into your LLM-powered applications' +--- + +The Model Context Protocol (MCP) enables seamless integration between LLM applications and various data sources and tools. This guide will walk you through integrating MCP into your own LLM-powered chatbot application. + +## Our Example Chatbot + +For this guide, we'll be working with a hypothetical customer service chatbot for a software company. Our chatbot currently: + +- Uses an LLM API (like Anthropic's Claude API) to generate responses +- Maintains conversation history in memory +- Has basic error handling and retry logic +- Runs as a web service that customers interact with through a REST API + +However, our chatbot faces some limitations: +- It can't access real-time product documentation or knowledge base articles +- It can't look up customer information or ticket history +- It can't perform actions like creating tickets or updating customer records +- It doesn't stay up-to-date with product changes and new features + +By integrating MCP, we'll enhance our chatbot to: +- Access documentation and knowledge base articles as contextual resources +- Look up customer information through a CRM integration +- Create and update support tickets through a ticketing system integration +- Get real-time updates when documentation or product information changes + +Let's get started! + +## Prerequisites + +1. Clone the example MCP servers: +```bash +git clone https://github.com/modelcontextprotocol/example-servers.git +cd example-servers +npm install +``` + +2. Install the MCP SDK in your chatbot project: +```bash +npm install @modelcontextprotocol/sdk +``` + +## Starting Point: Our Basic Chatbot + +Here's our starting chatbot implementation that we'll enhance with MCP: + +```typescript +interface Message { + role: 'user' | 'assistant'; + content: string; +} + +class CustomerServiceBot { + private conversation: Message[] = []; + private llmClient: LLMClient; // Your LLM API client + + constructor(llmClient: LLMClient) { + this.llmClient = llmClient; + } + + async handleMessage(message: string): Promise { + // Add user message to conversation + this.conversation.push({ role: 'user', content: message }); + + // Get LLM response + const response = await this.llmClient.complete({ + messages: this.conversation, + maxTokens: 1000 + }); + + // Add assistant response to conversation + this.conversation.push({ role: 'assistant', content: response }); + + return response; + } +} +``` + +## Step 1: Adding Documentation Context + +First, let's enhance our chatbot to incorporate product documentation. We'll use the example PostgreSQL server which can store and serve our docs. + +```typescript +import { Client } from "@modelcontextprotocol/sdk/client"; +import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio"; +import { + ListResourcesResultSchema, + ReadResourceResultSchema +} from "@modelcontextprotocol/sdk/types"; + +class EnhancedCustomerServiceBot { + private conversation: Message[] = []; + private llmClient: LLMClient; + private mcpClient: Client; + + constructor(llmClient: LLMClient) { + this.llmClient = llmClient; + + // Initialize MCP client + this.mcpClient = new Client({ + name: "customer-service-bot", + version: "1.0.0" + }); + } + + async initialize() { + // Connect to PostgreSQL server for documentation + const transport = new StdioClientTransport({ + command: "./example-servers/postgres/index.js", + args: ["postgres://localhost/docs"] // Your docs database + }); + await this.mcpClient.connect(transport); + } + + async getRelevantDocs(message: string): Promise { + // List available documentation resources + const { resources } = await this.mcpClient.request( + { method: "resources/list" }, + ListResourcesResultSchema + ); + + // Read each documentation resource + const docs = await Promise.all( + resources.map(async (resource) => { + const { contents } = await this.mcpClient.request( + { + method: "resources/read", + params: { uri: resource.uri } + }, + ReadResourceResultSchema + ); + return contents[0].text; + }) + ); + + return docs.join("\n\n"); + } + + async handleMessage(message: string): Promise { + // Get relevant documentation + const docs = await this.getRelevantDocs(message); + + // Build prompt with documentation context + const prompt = ` + Here is relevant documentation about our product: + ${docs} + + Please use this information to help answer the customer's question. + + Customer: ${message} + `; + + // Add user message to conversation + this.conversation.push({ role: 'user', content: message }); + + // Get LLM response with documentation context + const response = await this.llmClient.complete({ + messages: [...this.conversation, { role: 'user', content: prompt }], + maxTokens: 1000 + }); + + // Add assistant response to conversation + this.conversation.push({ role: 'assistant', content: response }); + + return response; + } +} +``` + +## Step 2: Adding Ticket Management + +Now let's add the ability to create and update support tickets. We'll use the example tools server for this: + +```typescript +import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types"; + +interface Ticket { + id: string; + subject: string; + description: string; + status: 'open' | 'closed'; +} + +class EnhancedCustomerServiceBot { + // ... previous code ... + + async createTicket(subject: string, description: string): Promise { + const result = await this.mcpClient.request( + { + method: "tools/call", + params: { + name: "create_ticket", + arguments: { + subject, + description + } + } + }, + CallToolResultSchema + ); + + return result.toolResult as Ticket; + } + + async handleMessage(message: string): Promise { + // Get relevant documentation + const docs = await this.getRelevantDocs(message); + + // Build prompt with documentation context and ticket creation ability + const prompt = ` + Here is relevant documentation about our product: + ${docs} + + You can create support tickets when needed using the createTicket function. + Only create tickets for actual technical issues that need follow-up. + + Customer: ${message} + `; + + // Get LLM response + const response = await this.llmClient.complete({ + messages: [...this.conversation, { role: 'user', content: prompt }], + maxTokens: 1000, + tools: [{ + name: 'createTicket', + description: 'Create a support ticket for technical issues', + parameters: { + subject: 'string', + description: 'string' + } + }] + }); + + // Check if the LLM wants to create a ticket + if (response.toolCalls?.length > 0) { + const call = response.toolCalls[0]; + const ticket = await this.createTicket( + call.arguments.subject, + call.arguments.description + ); + + // Add ticket creation to conversation + this.conversation.push({ + role: 'system', + content: `Created ticket #${ticket.id}: ${ticket.subject}` + }); + } + + // Add messages to conversation + this.conversation.push({ role: 'user', content: message }); + this.conversation.push({ role: 'assistant', content: response.content }); + + return response.content; + } +} +``` + +## Step 3: Real-time Documentation Updates + +Finally, let's make our chatbot aware of documentation changes in real-time: + +```typescript +class EnhancedCustomerServiceBot { + // ... previous code ... + + async initialize() { + // Connect to PostgreSQL server + const transport = new StdioClientTransport({ + command: "./example-servers/postgres/index.js", + args: ["postgres://localhost/docs"] + }); + await this.mcpClient.connect(transport); + + // Subscribe to documentation updates + const { resources } = await this.mcpClient.request( + { method: "resources/list" }, + ListResourcesResultSchema + ); + + for (const resource of resources) { + await this.mcpClient.request( + { + method: "resources/subscribe", + params: { uri: resource.uri } + }, + EmptyResultSchema + ); + } + + // Handle update notifications + this.mcpClient.setNotificationHandler( + ResourceUpdatedNotificationSchema, + async (notification) => { + console.log(`Documentation updated: ${notification.params.uri}`); + // Optionally clear any cached documentation + } + ); + } +} +``` + +## Using the Enhanced Chatbot + +Here's how to use our enhanced chatbot: + +```typescript +const bot = new EnhancedCustomerServiceBot(llmClient); +await bot.initialize(); + +// Example conversation +const response1 = await bot.handleMessage( + "How do I reset my password?" +); +// Bot responds with information from documentation + +const response2 = await bot.handleMessage( + "I can't log in even after resetting my password" +); +// Bot creates a ticket and responds with next steps + +``` + +## Error Handling + +Add robust error handling around MCP operations: + +```typescript +class EnhancedCustomerServiceBot { + // ... previous code ... + + async getRelevantDocs(message: string): Promise { + try { + const { resources } = await this.mcpClient.request( + { method: "resources/list" }, + ListResourcesResultSchema + ); + + const docs = await Promise.all( + resources.map(async (resource) => { + try { + const { contents } = await this.mcpClient.request( + { + method: "resources/read", + params: { uri: resource.uri } + }, + ReadResourceResultSchema + ); + return contents[0].text; + } catch (error) { + console.error(`Failed to read resource ${resource.uri}:`, error); + return ""; // Skip failed resources + } + }) + ); + + return docs.join("\n\n"); + } catch (error) { + console.error("Failed to list resources:", error); + return ""; // Fallback to no documentation + } + } +} +``` + +## Next Steps + +Now that you've enhanced your chatbot with MCP, you can: + +1. Add more integrations: + - Connect to your actual documentation system + - Integrate with your production ticketing system + - Add CRM integration for customer context + +2. Improve the implementation: + - Add better documentation relevance filtering + - Implement more sophisticated prompt engineering + - Add authentication and access control + - Add monitoring and logging + - Implement caching for frequently accessed resources + +3. Consider building custom MCP servers for your specific needs + +The example servers repository includes other servers you can experiment with, and you can build your own servers to expose custom functionality to your chatbot. \ No newline at end of file diff --git a/docs/guides/security-best-practices.mdx b/docs/guides/security-best-practices.mdx new file mode 100644 index 0000000..1ccf011 --- /dev/null +++ b/docs/guides/security-best-practices.mdx @@ -0,0 +1,8 @@ +--- +title: "Security Best Practices" +description: "Secure your MCP implementations" +--- + +# Security Best Practices + +Secure your MCP implementations diff --git a/docs/guides/testing-debugging.mdx b/docs/guides/testing-debugging.mdx new file mode 100644 index 0000000..a936680 --- /dev/null +++ b/docs/guides/testing-debugging.mdx @@ -0,0 +1,8 @@ +--- +title: "Testing and Debugging" +description: "Test and debug your MCP servers effectively" +--- + +# Testing and Debugging + +Test and debug your MCP servers effectively diff --git a/docs/guides/working-with-resources.mdx b/docs/guides/working-with-resources.mdx new file mode 100644 index 0000000..f77ad53 --- /dev/null +++ b/docs/guides/working-with-resources.mdx @@ -0,0 +1,8 @@ +--- +title: "Working with Resources" +description: "Learn how to expose and consume data through MCP" +--- + +# Working with Resources + +Learn how to expose and consume data through MCP diff --git a/docs/installation.mdx b/docs/installation.mdx new file mode 100644 index 0000000..66ffc35 --- /dev/null +++ b/docs/installation.mdx @@ -0,0 +1,160 @@ +--- +title: "Installation" +description: "Get started with Model Context Protocol (MCP) by installing the SDK for your preferred language" +--- + + + MCP supports both TypeScript and Python implementations. Choose the one that best fits your project. + + + + + + + Install the TypeScript SDK using npm: + ```bash + npm install @modelcontextprotocol/sdk + ``` + + + Install the Python SDK using pip: + ```bash + pip install modelcontextprotocol + ``` + + + + + + Verify your installation by running a simple test: + + + ```typescript typescript-test.ts + import { Client } from "@modelcontextprotocol/sdk"; + + const client = new Client({ + name: "test-client", + version: "0.1.0" + }); + console.log("MCP SDK installed successfully!"); + ``` + + ```python python-test.py + from modelcontextprotocol import Client + + client = Client( + name="test-client", + version="0.1.0" + ) + print("MCP SDK installed successfully!") + ``` + + + + + + For local development, you'll need Node.js 18+ for TypeScript or Python 3.8+ for Python. + + + Install the MCP Inspector for testing and debugging your implementations: + ```bash + npm install -g @modelcontextprotocol/inspector + ``` + + + +## System Requirements + + + + - Node.js 18 or higher + - npm 7 or higher + - TypeScript 4.7 or higher (for TypeScript users) + + Optional development tools: + - VS Code with TypeScript plugin + - ESLint for code quality + + + + - Python 3.8 or higher + - pip 20.0 or higher + - virtualenv (recommended) + + Optional development tools: + - VS Code with Python extension + - pylint for code quality + + + + MCP supports all major operating systems: + - Windows 10/11 + - macOS 10.15+ + - Linux (major distributions) + + + +## Architecture Overview + + + + + +```mermaid +flowchart LR + A[LLM Application] --> B[MCP Client] + B --> C[MCP Server] + C --> D[(External Resource)] + + style A fill:#e0f4ff,stroke:#0077cc,stroke-width:2px + style B fill:#fff4e0,stroke:#ff8c00,stroke-width:2px + style C fill:#e0ffe0,stroke:#2d862d,stroke-width:2px + style D fill:#ffe0e0,stroke:#cc0000,stroke-width:2px + + classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px + +## Next Steps + + + Build your first MCP integration in under 5 minutes + + + Explore pre-built MCP servers for common use cases + + + Dive into the complete API documentation + + + + Join our [Discord community](https://discord.gg/mcp) for help and discussions about MCP development. + + +## Troubleshooting Common Issues + + + + If you encounter version conflicts, ensure all your dependencies are up to date: + ```bash + # For TypeScript + npm update @modelcontextprotocol/sdk +Copy# For Python +pip install --upgrade modelcontextprotocol +``` + + + If you're having trouble connecting to MCP servers: + 1. Check your network configuration + 2. Verify the server is running + 3. Ensure your firewall isn't blocking connections + 4. Check the server logs for errors + + + Common build errors and their solutions: + - TypeScript type errors: Update your @types dependencies + - Python import errors: Check your PYTHONPATH + - Missing dependencies: Run package manager install commands + + + + Remember to keep your SDKs updated to the latest version for security patches and new features. + diff --git a/docs/key-concepts.mdx b/docs/key-concepts.mdx new file mode 100644 index 0000000..691ab1b --- /dev/null +++ b/docs/key-concepts.mdx @@ -0,0 +1,12 @@ +--- +title: "Key Concepts" +description: "Learn the core concepts behind the Model Context Protocol (MCP) and how they work together" +--- + + + This guide provides a high-level overview of MCP's core concepts. For detailed implementation guides, check out our tutorials section. + + +The Model Context Protocol (MCP) enables seamless integration between LLM applications and external data sources or tools. Let's break down the key concepts: + + diff --git a/docs/recipes/api-integration.mdx b/docs/recipes/api-integration.mdx new file mode 100644 index 0000000..f3787b0 --- /dev/null +++ b/docs/recipes/api-integration.mdx @@ -0,0 +1,8 @@ +--- +title: "API Integration" +description: "Wrap external APIs with MCP" +--- + +# API Integration + +Wrap external APIs with MCP diff --git a/docs/recipes/database-integration.mdx b/docs/recipes/database-integration.mdx new file mode 100644 index 0000000..dbcf630 --- /dev/null +++ b/docs/recipes/database-integration.mdx @@ -0,0 +1,8 @@ +--- +title: "Database Integration" +description: "Connect databases to your LLM through MCP" +--- + +# Database Integration + +Connect databases to your LLM through MCP diff --git a/docs/recipes/local-files.mdx b/docs/recipes/local-files.mdx new file mode 100644 index 0000000..fb592b4 --- /dev/null +++ b/docs/recipes/local-files.mdx @@ -0,0 +1,8 @@ +--- +title: "Local File Access" +description: "Implement local file access in MCP" +--- + +# Local File Access + +Implement local file access in MCP diff --git a/docs/recipes/realtime-updates.mdx b/docs/recipes/realtime-updates.mdx new file mode 100644 index 0000000..a7d2b58 --- /dev/null +++ b/docs/recipes/realtime-updates.mdx @@ -0,0 +1,8 @@ +--- +title: "Real-time Updates" +description: "Handle live data updates in MCP" +--- + +# Real-time Updates + +Handle live data updates in MCP diff --git a/essentials/code.mdx b/essentials/code.mdx deleted file mode 100644 index d2a462a..0000000 --- a/essentials/code.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: 'Code Blocks' -description: 'Display inline code and code blocks' -icon: 'code' ---- - -## Basic - -### Inline Code - -To denote a `word` or `phrase` as code, enclose it in backticks (`). - -``` -To denote a `word` or `phrase` as code, enclose it in backticks (`). -``` - -### Code Block - -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` -```` diff --git a/essentials/images.mdx b/essentials/images.mdx deleted file mode 100644 index 60ad42d..0000000 --- a/essentials/images.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: 'Images and Embeds' -description: 'Add image, video, and other HTML elements' -icon: 'image' ---- - - - -## Image - -### Using Markdown - -The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code - -```md -![title](/path/image.jpg) -``` - -Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed. - -### Using Embeds - -To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images - -```html - -``` - -## Embeds and HTML elements - - - -
- - - -Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility. - - - -### iFrames - -Loads another HTML page within the document. Most commonly used for embedding videos. - -```html - -``` diff --git a/essentials/markdown.mdx b/essentials/markdown.mdx deleted file mode 100644 index c8ad9c1..0000000 --- a/essentials/markdown.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: 'Markdown Syntax' -description: 'Text, title, and styling in standard markdown' -icon: 'text-size' ---- - -## Titles - -Best used for section headers. - -```md -## Titles -``` - -### Subtitles - -Best use to subsection headers. - -```md -### Subtitles -``` - - - -Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right. - - - -## Text Formatting - -We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. - -| Style | How to write it | Result | -| ------------- | ----------------- | --------------- | -| Bold | `**bold**` | **bold** | -| Italic | `_italic_` | _italic_ | -| Strikethrough | `~strikethrough~` | ~strikethrough~ | - -You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text. - -You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text. - -| Text Size | How to write it | Result | -| ----------- | ------------------------ | ---------------------- | -| Superscript | `superscript` | superscript | -| Subscript | `subscript` | subscript | - -## Linking to Pages - -You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com). - -Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section. - -Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily. - -## Blockquotes - -### Singleline - -To create a blockquote, add a `>` in front of a paragraph. - -> Dorothy followed her through many of the beautiful rooms in her castle. - -```md -> Dorothy followed her through many of the beautiful rooms in her castle. -``` - -### Multiline - -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. - -```md -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. -``` - -### LaTeX - -Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component. - -8 x (vk x H1 - H2) = (0,1) - -```md -8 x (vk x H1 - H2) = (0,1) -``` diff --git a/essentials/navigation.mdx b/essentials/navigation.mdx deleted file mode 100644 index ca44bb6..0000000 --- a/essentials/navigation.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: 'Navigation' -description: 'The navigation field in mint.json defines the pages that go in the navigation menu' -icon: 'map' ---- - -The navigation menu is the list of links on every website. - -You will likely update `mint.json` every time you add a new page. Pages do not show up automatically. - -## Navigation syntax - -Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names. - - - -```json Regular Navigation -"navigation": [ - { - "group": "Getting Started", - "pages": ["quickstart"] - } -] -``` - -```json Nested Navigation -"navigation": [ - { - "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] - } - ] - } -] -``` - - - -## Folders - -Simply put your MDX files in folders and update the paths in `mint.json`. - -For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`. - - - -You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted. - - - -```json Navigation With Folder -"navigation": [ - { - "group": "Group Name", - "pages": ["your-folder/your-page"] - } -] -``` - -## Hidden Pages - -MDX files not included in `mint.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them. diff --git a/essentials/reusable-snippets.mdx b/essentials/reusable-snippets.mdx deleted file mode 100644 index a0a5529..0000000 --- a/essentials/reusable-snippets.mdx +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Reusable Snippets -description: Reusable, custom snippets to keep content in sync -icon: 'recycle' ---- - -import SnippetIntro from '/snippets/snippet-intro.mdx'; - - - -## Creating a custom snippet - -**Pre-condition**: You must create your snippet file in the `snippets` directory. - - - Any page in the `snippets` directory will be treated as a snippet and will not - be rendered into a standalone page. If you want to create a standalone page - from the snippet, import the snippet into another file and call it as a - component. - - -### Default export - -1. Add content to your snippet file that you want to re-use across multiple - locations. Optionally, you can add variables that can be filled in via props - when you import the snippet. - -```mdx snippets/my-snippet.mdx -Hello world! This is my content I want to reuse across pages. My keyword of the -day is {word}. -``` - - - The content that you want to reuse must be inside the `snippets` directory in - order for the import to work. - - -2. Import the snippet into your destination file. - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import MySnippet from '/snippets/path/to/my-snippet.mdx'; - -## Header - -Lorem impsum dolor sit amet. - - -``` - -### Reusable variables - -1. Export a variable from your snippet file: - -```mdx snippets/path/to/custom-variables.mdx -export const myName = 'my name'; - -export const myObject = { fruit: 'strawberries' }; -``` - -2. Import the snippet from your destination file and use the variable: - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import { myName, myObject } from '/snippets/path/to/custom-variables.mdx'; - -Hello, my name is {myName} and I like {myObject.fruit}. -``` - -### Reusable components - -1. Inside your snippet file, create a component that takes in props by exporting - your component in the form of an arrow function. - -```mdx snippets/custom-component.mdx -export const MyComponent = ({ title }) => ( -
-

{title}

-

... snippet content ...

-
-); -``` - - - MDX does not compile inside the body of an arrow function. Stick to HTML - syntax when you can or use a default export if you need to use MDX. - - -2. Import the snippet into your destination file and pass in the props - -```mdx destination-file.mdx ---- -title: My title -description: My Description ---- - -import { MyComponent } from '/snippets/custom-component.mdx'; - -Lorem ipsum dolor sit amet. - - -``` diff --git a/essentials/settings.mdx b/essentials/settings.mdx deleted file mode 100644 index a8c158c..0000000 --- a/essentials/settings.mdx +++ /dev/null @@ -1,318 +0,0 @@ ---- -title: 'Global Settings' -description: 'Mintlify gives you complete control over the look and feel of your documentation using the mint.json file' -icon: 'gear' ---- - -Every Mintlify site needs a `mint.json` file with the core configuration settings. Learn more about the [properties](#properties) below. - -## Properties - - -Name of your project. Used for the global title. - -Example: `mintlify` - - - - - An array of groups with all the pages within that group - - - The name of the group. - - Example: `Settings` - - - - The relative paths to the markdown files that will serve as pages. - - Example: `["customization", "page"]` - - - - - - - - Path to logo image or object with path to "light" and "dark" mode logo images - - - Path to the logo in light mode - - - Path to the logo in dark mode - - - Where clicking on the logo links you to - - - - - - Path to the favicon image - - - - Hex color codes for your global theme - - - The primary color. Used for most often for highlighted content, section - headers, accents, in light mode - - - The primary color for dark mode. Used for most often for highlighted - content, section headers, accents, in dark mode - - - The primary color for important buttons - - - The color of the background in both light and dark mode - - - The hex color code of the background in light mode - - - The hex color code of the background in dark mode - - - - - - - - Array of `name`s and `url`s of links you want to include in the topbar - - - The name of the button. - - Example: `Contact us` - - - The url once you click on the button. Example: `https://mintlify.com/docs` - - - - - - - - - Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars. - - - If `link`: What the button links to. - - If `github`: Link to the repository to load GitHub information from. - - - Text inside the button. Only required if `type` is a `link`. - - - - - - - Array of version names. Only use this if you want to show different versions - of docs with a dropdown in the navigation bar. - - - - An array of the anchors, includes the `icon`, `color`, and `url`. - - - The [Font Awesome](https://fontawesome.com/search?q=heart) icon used to feature the anchor. - - Example: `comments` - - - The name of the anchor label. - - Example: `Community` - - - The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in. - - - The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color. - - - Used if you want to hide an anchor until the correct docs version is selected. - - - Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - - Override the default configurations for the top-most anchor. - - - The name of the top-most anchor - - - Font Awesome icon. - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - An array of navigational tabs. - - - The name of the tab label. - - - The start of the URL that marks what pages go in the tab. Generally, this - is the name of the folder you put your pages in. - - - - - - Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo). - - - The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url - options that the user can toggle. - - - - - - The authentication strategy used for all API endpoints. - - - The name of the authentication parameter used in the API playground. - - If method is `basic`, the format should be `[usernameName]:[passwordName]` - - - The default value that's designed to be a prefix for the authentication input field. - - E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`. - - - - - - Configurations for the API playground - - - - Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` - - Learn more at the [playground guides](/api-playground/demo) - - - - - - Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file. - - This behavior will soon be enabled by default, at which point this field will be deprecated. - - - - - - - A string or an array of strings of URL(s) or relative path(s) pointing to your - OpenAPI file. - - Examples: - - ```json Absolute - "openapi": "https://example.com/openapi.json" - ``` - ```json Relative - "openapi": "/openapi.json" - ``` - ```json Multiple - "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] - ``` - - - - - - An object of social media accounts where the key:property pair represents the social media platform and the account url. - - Example: - ```json - { - "x": "https://x.com/mintlify", - "website": "https://mintlify.com" - } - ``` - - - One of the following values `website`, `facebook`, `x`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news` - - Example: `x` - - - The URL to the social platform. - - Example: `https://x.com/mintlify` - - - - - - Configurations to enable feedback buttons - - - - Enables a button to allow users to suggest edits via pull requests - - - Enables a button to allow users to raise an issue about the documentation - - - - - - Customize the dark mode toggle. - - - Set if you always want to show light or dark mode for new users. When not - set, we default to the same mode as the user's operating system. - - - Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example: - - - ```json Only Dark Mode - "modeToggle": { - "default": "dark", - "isHidden": true - } - ``` - - ```json Only Light Mode - "modeToggle": { - "default": "light", - "isHidden": true - } - ``` - - - - - - - - - A background image to be displayed behind every page. See example with - [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io). - diff --git a/images/modelcontextprotocol.png b/images/modelcontextprotocol.png new file mode 100644 index 0000000..8287430 Binary files /dev/null and b/images/modelcontextprotocol.png differ diff --git a/introduction.mdx b/introduction.mdx index 2589c0b..9f6743d 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -1,20 +1,12 @@ --- title: Introduction -description: 'Welcome to the home of your new documentation' +description: 'Introduction to the Model Context Protocol' --- -Hero Light -Hero Dark +The Model Context Protocol (MCP) is a protocol designed to enable LLM assistant surfaces to receive contextual information from specialized servers. Whether you’re building an IDE coding assistant, a chat interface, or any other LLM-powered application, MCP provides a standardized way to obtain and utilize relevant context. -## Setting up + +## Get started The first step to world-class documentation is setting up your editing environments. diff --git a/logo/dark.png b/logo/dark.png new file mode 100644 index 0000000..58156d1 Binary files /dev/null and b/logo/dark.png differ diff --git a/logo/light.png b/logo/light.png new file mode 100644 index 0000000..3799509 Binary files /dev/null and b/logo/light.png differ diff --git a/mint.json b/mint.json index 2799bba..b93e86e 100644 --- a/mint.json +++ b/mint.json @@ -1,19 +1,16 @@ { "$schema": "https://mintlify.com/schema.json", - "name": "Starter Kit", + "name": "Model Context Protocol", "logo": { - "dark": "/logo/dark.svg", - "light": "/logo/light.svg" + "dark": "/logo/dark.png", + "light": "/logo/light.png" }, "favicon": "/favicon.svg", + "theme": "quill", "colors": { - "primary": "#0D9373", - "light": "#07C983", - "dark": "#0D9373", - "anchors": { - "from": "#0D9373", - "to": "#07C983" - } + "primary": "#09090b", + "light": "#FAFAFA", + "dark": "#09090b" }, "topbarLinks": [ { @@ -52,34 +49,78 @@ { "group": "Get Started", "pages": [ - "introduction", "quickstart", - "development" + "docs/installation", + "docs/key-concepts", + "docs/development" ] }, { - "group": "Essentials", + "group": "Guides", "pages": [ - "essentials/markdown", - "essentials/code", - "essentials/images", - "essentials/settings", - "essentials/navigation", - "essentials/reusable-snippets" + "docs/guides/first-mcp-server", + "docs/guides/integrating-with-llm", + "docs/guides/working-with-resources", + "docs/guides/implementing-tools", + "docs/guides/security-best-practices", + "docs/guides/testing-debugging" ] }, { - "group": "API Documentation", + "group": "Recipes", "pages": [ - "api-reference/introduction" + "docs/recipes/local-files", + "docs/recipes/database-integration", + "docs/recipes/api-integration", + "docs/recipes/realtime-updates" ] }, { - "group": "Endpoint Examples", + "group": "Deployment", "pages": [ - "api-reference/endpoint/get", - "api-reference/endpoint/create", - "api-reference/endpoint/delete" + "docs/deployment/environment-setup", + "docs/deployment/configuration", + "docs/deployment/monitoring" + ] + }, + { + "group": "API Reference", + "pages": [ + "api-reference/protocol-overview", + "api-reference/message-types", + "api-reference/error-handling" + ] + }, + { + "group": "Server APIs", + "pages": [ + "api-reference/server-api/resource-management", + "api-reference/server-api/tool-implementation", + "api-reference/server-api/event-handling" + ] + }, + { + "group": "Client APIs", + "pages": [ + "api-reference/client-api/connection-management", + "api-reference/client-api/resource-consumption", + "api-reference/client-api/tool-invocation" + ] + }, + { + "group": "TypeScript SDK", + "pages": [ + "api-reference/typescript/class-reference", + "api-reference/typescript/type-definitions", + "api-reference/typescript/examples" + ] + }, + { + "group": "Python SDK", + "pages": [ + "api-reference/python/class-reference", + "api-reference/python/type-hints", + "api-reference/python/examples" ] } ], diff --git a/quickstart.mdx b/quickstart.mdx index c44cfaa..283553b 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -1,86 +1,305 @@ --- -title: 'Quickstart' -description: 'Start building awesome documentation in under 5 minutes' +title: "Quickstart" +description: "Get started with MCP in less than 5 minutes" --- -## Setup your development +Give Claude superpowers by connecting it to your local computer! This guide will show you how to set up Model Context Protocol (MCP) and experience its magic in just 5 minutes. -Learn how to update your docs locally and deploy them to the public. + +Model Context Protocol (MCP) is like giving Claude hands and eyes on your computer. It can: +- Take screenshots and analyze what's on your screen +- Read and analyze files from your computer +- Help you automate repetitive tasks +- Connect to your databases and local tools -### Edit and preview +And it does all this while maintaining security - Claude can only access what you explicitly allow. + + +## Prerequisites + + +```bash macOS +# Check if you have Node.js installed +node --version # Should be v16 or higher + +# Check if you have git installed +git --version +``` + +```bash Installation +# Install Node.js from https://nodejs.org +# Install git from https://git-scm.com + +# Or use Homebrew +brew install node git +``` + + +## Quick Setup + + + + Let's start by getting some pre-built MCP servers that Claude can use: + + ```bash + # Clone the example servers + git clone https://github.com/modelcontextprotocol/example-servers + cd example-servers + + # Install dependencies and build + npm install + npm run build + + # Make servers available globally + npm install -g + ``` + + + + Open your Claude Desktop App configuration: + + ```bash + code ~/Library/Application\ Support/Claude/claude_desktop_config.json + ``` + + Add this configuration (replace YOUR_USERNAME with your actual username): + + ```json + { + "mcpServers": { + "osascript": { + "command": "mcp-server-osascript", + "env": { + "HOME": "/Users/YOUR_USERNAME" + } + } + } + } + ``` + + Save and **restart Claude Desktop App**. + + + + When you first use screen capture features, macOS will ask for permissions: + + + Screenshot permissions dialog + + + Grant these permissions to Claude Desktop App: + - Screen Recording (for screenshots) + - Automation (for window management) + + + +## Try It Out! πŸŽ‰ + +Now for the fun part! Try these examples to see MCP in action: - - During the onboarding process, we created a repository on your Github with - your docs content. You can find this repository on our - [dashboard](https://dashboard.mintlify.com). To clone the repository - locally, follow these - [instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) - in your terminal. + + Ask Claude: + ``` + Can you take a screenshot of my desktop and describe what you see? + ``` + + Claude will: + 1. Use MCP to capture your screen + 2. Add it as context to your conversation + 3. Analyze and describe what it sees + + Try follow-up questions like: + - "How many windows do I have open?" + - "What apps am I running?" + - "Is my battery level low?" - - Previewing helps you make sure your changes look as intended. We built a - command line interface to render these changes locally. 1. Install the - [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the - documentation changes locally with this command: ``` npm i -g mintlify ``` - 2. Run the following command at the root of your documentation (where - `mint.json` is): ``` mintlify dev ``` + + + Ask Claude: + ``` + I have several windows open and it's messy. Could you help me organize them? Maybe arrange my browser windows side by side? + ``` + + Claude will: + 1. Take a screenshot to assess the situation + 2. Use AppleScript to organize your windows + 3. Take another screenshot to confirm the changes + + Pro tip: You can ask Claude to create specific layouts or focus on particular apps! + + + + Ask Claude: + ``` + I often need to arrange my windows with: + - Browser on the left half + - VS Code on the top right quarter + - Terminal on the bottom right quarter + + Can you create an AppleScript to automate this layout? + ``` + + Claude will create a reusable script that you can save and run anytime! -### Deploy your changes +## What Just Happened? - + +Let's break down the magic: - - Our Github app automatically deploys your changes to your docs site, so you - don't need to manage deployments yourself. You can find the link to install on - your [dashboard](https://dashboard.mintlify.com). Once the bot has been - successfully installed, there should be a check mark next to the commit hash - of the repo. - - - [Commit and push your changes to - Git](https://docs.github.com/en/get-started/using-git/pushing-commits-to-a-remote-repository#about-git-push) - for your changes to update in your docs site. If you push and don't see that - the Github app successfully deployed your changes, you can also manually - update your docs through our [dashboard](https://dashboard.mintlify.com). - +1. When you installed the `osascript` server, you gave Claude a way to: + - Take screenshots (see what you see) + - Run AppleScript (control your windows) + - Automate macOS tasks - +2. The MCP protocol lets Claude: + - Request these actions securely + - Get results back in real-time + - Chain actions together intelligently -## Update your docs - -Add content directly in your files with MDX syntax and React components. You can use any of our components, or even build your own. - - - - - Add flair to your docs with personalized branding. +3. All of this happens locally on your machine - no data leaves your computer! - - Implement your OpenAPI spec and enable API user interaction. - +## Add More Capabilities - - Draw insights from user interactions with your documentation. - - - - Keep your docs on your own website's subdomain. - +Want to give Claude even more superpowers? Add these servers to your configuration: + + + Add this to your config to let Claude read and analyze files: + ```json + "tee": { + "command": "mcp-server-tee", + "args": ["tail", "-f", "/var/log/system.log"], + "env": { + "HOME": "/Users/YOUR_USERNAME" + } + } + ``` + + + + Connect Claude to your PostgreSQL database: + ```json + "postgres": { + "command": "mcp-server-postgres", + "args": ["postgresql://localhost/mydb"], + "env": { + "HOME": "/Users/YOUR_USERNAME" + } + } + ``` + + + + Enable web automation capabilities: + ```json + "puppeteer": { + "command": "mcp-server-puppeteer", + "env": { + "HOME": "/Users/YOUR_USERNAME" + } + } + ``` + + +## Quick Troubleshooting + + + + 1. Check if MCP is enabled: + - Click the πŸ”Œ icon in Claude + - You should see your configured servers + + 2. Verify your config: + ```bash + cat ~/Library/Application\ Support/Claude/claude_desktop_config.json + ``` + + 3. Restart Claude completely: + - Quit the app (not just close the window) + - Start it again + + + + Run this command to see Claude's logs: + ```bash + tail -f ~/Claude.log + ``` + + Common fixes: + - Check `HOME` env variable in your config + - Grant missing permissions in System Settings + - Try running example commands manually in Terminal + + + +## Pro Tips + + + + During development: + - Use Command+R to reload Claude + - This restarts MCP servers without closing Claude + - Perfect for testing config changes! + + + + Run multiple servers for maximum capability: + ```json + { + "mcpServers": { + "osascript": { ... }, + "postgres": { ... }, + "puppeteer": { ... }, + "tee": { ... } + } + } + ``` + + Now Claude can: + - Take screenshots + - Query your database + - Automate web tasks + - Read local files + + All in the same conversation! + + + + Add `"debug": true` to see what's happening: + ```json + { + "mcpServers": { + "osascript": { + "command": "mcp-server-osascript", + "env": { ... }, + "debug": true + } + } + } + ``` + + Then watch the logs: + ```bash + tail -f ~/Claude.log + ``` + + + +## Next Steps + + +Now that you've experienced MCP, you might want to: + +1. [Build your own MCP server](/mcp-dev) - Create custom integrations +2. [Explore example servers](https://github.com/modelcontextprotocol/example-servers) - See what's possible +3. Join our [community](/community) - Share your MCP creations! + + + +Remember: Claude will help you write MCP servers! Just describe what you want to build, and Claude can guide you through the process. + \ No newline at end of file diff --git a/your-first-server.mdx b/your-first-server.mdx new file mode 100644 index 0000000..c17200d --- /dev/null +++ b/your-first-server.mdx @@ -0,0 +1,319 @@ +--- +title: "Your first MCP server" +description: "Get started with MCP by building a weather app in 5 minutes" +--- + +Connect AI to anything. MCP (Model Context Protocol) lets your AI applications seamlessly interact with data sources, tools, and services. + + + **Real-world example:** In this quickstart, we'll build an AI-powered weather app that lets users ask about current conditions in any city. Our app will use MCP to connect to a weather API. + + +![Weather App Demo](weather-app-demo.gif) + +## Installation + + + + ```bash + pip install mcp-sdk # Using pip + uv add mcp-sdk # Using uv (recommended) + ``` + + **Requirements:** + - Python 3.8 or higher + - pip or uv package manager + + + ```bash + npm install @modelcontextprotocol/sdk + ``` + + **Requirements:** + - Node.js 16 or higher + - TypeScript 4.7 or higher + - npm or yarn package manager + + + +## Step 1: Create an MCP Server + +Our server will expose a tool that the AI can use to fetch the current weather for any city. + + + + ```python weather_server.py + from mcp.server import Server + from mcp.server.stdio import stdio_server + import aiohttp + + server = Server("weather-server") + + @server.list_tools() + async def list_tools(): + return [{ + "name": "get_weather", + "description": "Get current weather for a city", + "inputSchema": { + "type": "object", + "properties": { + "city": {"type": "string"} + } + } + }] + + @server.call_tool() + async def call_tool(name: str, args: dict): + if name == "get_weather": + async with aiohttp.ClientSession() as session: + city = args["city"] + url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid=YOUR_API_KEY" + async with session.get(url) as resp: + data = await resp.json() + return data["weather"][0]["description"] + + async def main(): + async with stdio_server() as (read, write): + await server.run(read, write) + + if __name__ == "__main__": + import asyncio + asyncio.run(main()) + ``` + + To make real API requests, sign up for a free API key at [OpenWeatherMap](https://openweathermap.org). + + + + ```typescript weather_server.ts + import { Server } from "@modelcontextprotocol/sdk/server"; + import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio"; + import axios from "axios"; + + const server = new Server({ + name: "weather-server", + version: "1.0.0", + }); + + server.setRequestHandler(ListToolsRequestSchema, async () => { + return { + tools: [{ + name: "get_weather", + description: "Get current weather for a city", + inputSchema: { + type: "object", + properties: { + city: { type: "string" } + } + } + }] + }; + }); + + server.setRequestHandler(CallToolRequestSchema, async (request) => { + if (request.params.name === "get_weather") { + const city = request.params.arguments?.city as string; + const url = `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=YOUR_API_KEY`; + const resp = await axios.get(url); + return { + toolResult: resp.data.weather[0].description + }; + } + throw new Error("Tool not found"); + }); + + async function main() { + const transport = new StdioServerTransport(); + await server.connect(transport); + } + + main().catch(console.error); + ``` + + To make real API requests, sign up for a free API key at [OpenWeatherMap](https://openweathermap.org). + + + +## Step 2: Integrate the Server into Your AI App + + + This example uses a mock AI model. In a real app, you would replace this with your actual AI model code that generates a response based on the user's message and any MCP context. + + + + + ```python app.py + from mcp.client import ClientSession + from mcp.client.stdio import stdio_client + import re + + def extract_city(message): + match = re.search(r"in\s+(\w+)", message) + if match: + return match.group(1) + else: + return None + + async def get_weather(city): + async with stdio_client(command="python weather_server.py") as (read, write): + async with ClientSession(read, write) as session: + await session.initialize() + return await session.call_tool("get_weather", {"city": city}) + + async def handle_message(message): + city = extract_city(message) + if city: + weather = await get_weather(city) + return f"The current weather in {city} is: {weather}" + else: + return generate_response(message) # Your existing AI logic + + async def main(): + while True: + message = input("> ") + response = await handle_message(message) + print(response) + + if __name__ == "__main__": + import asyncio + asyncio.run(main()) + ``` + + + + ```typescript app.ts + import { Client } from "@modelcontextprotocol/sdk/client"; + import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio"; + import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types"; + import readline from "readline"; + + function extractCity(message: string): string | null { + const match = message.match(/in\s+(\w+)/); + if (match) { + return match[1]; + } else { + return null; + } + } + + async function getWeather(city: string): Promise { + const transport = new StdioClientTransport({ + command: "ts-node weather_server.ts", + }); + const client = new Client({ + name: "weather-app", + version: "1.0.0", + }); + await client.connect(transport); + const result = await client.request( + { + method: "tools/call", + params: { + name: "get_weather", + arguments: { city } + } + }, + CallToolResultSchema + ); + return result.toolResult as string; + } + + async function handleMessage(message: string): Promise { + const city = extractCity(message); + if (city) { + const weather = await getWeather(city); + return `The current weather in ${city} is: ${weather}`; + } else { + return generateResponse(message); // Your existing AI logic + } + } + + const rl = readline.createInterface({ + input: process.stdin, + output: process.stdout + }); + + rl.prompt(); + rl.on("line", async (line) => { + const response = await handleMessage(line); + console.log(response); + rl.prompt(); + }); + ``` + + + +## Step 3: Run It! + + + + In one terminal, start the server: + ```bash + python weather_server.py + ``` + In another terminal, start the app: + ```bash + python app.py + ``` + + + In one terminal, start the server: + ```bash + ts-node weather_server.ts + ``` + In another terminal, start the app: + ```bash + ts-node app.ts + ``` + + + +Now chat with your AI assistant! Try asking about the weather in various cities. + +``` +> What's the weather like in Tokyo? +The current weather in Tokyo is: few clouds + +> How about London? +The current weather in London is: scattered clouds +``` + +## Why MCP Rocks + +- **Effortless integrations.** No custom code needed to connect AI to any API, database, or service. +- **Async built-in.** MCP client/server communication is fully asynchronous out of the box. +- **Type-safe.** Requests and responses are validated against strict schemas. + +## Next Steps + + + + Understand resources, tools, prompts and more + + + Databases, APIs, embeddings, vectorstores... + + + Expose your AI through an API or website + + + Ensure your app is rock solid + + + +## Getting Help + + + + Get support and see what others are building + + + Look up library classes and functions + + + Quick answers to common questions + + + Report bugs or suggest improvements + + \ No newline at end of file