Como Construir um Servidor MCP com Vector Store: Integrando Documentação 3D no Cursor

O desenvolvimento de ferramentas de IA cada vez mais eficientes tem revolucionado o workflow de programadores em todo o mundo. Uma das combinações mais poderosas é a integração de servidores MCP (Message Context Protocol) com vector stores, permitindo que IDEs como o Cursor acessem documentação atualizada e relevante sem sair do ambiente de codificação. Neste artigo, vamos explorar como configurar um servidor MCP com Typescript que utiliza a feature de busca em arquivos do OpenAI, e como isso pode transformar sua experiência de desenvolvimento.

O Poder do Gemini 2.5 na Criação de Servidores MCP

O Google recentemente lançou o Gemini 2.5, um modelo de IA com capacidades impressionantes para raciocínio e desenvolvimento de código. Este modelo tem se destacado nos benchmarks de codificação, superando concorrentes como o GPT-4o e Claude 3.5 Sonnet. Com uma pontuação média de codificação de 85.8, o Gemini 2.5 prova ser uma ferramenta valiosa para desenvolvedores que buscam assistência em projetos complexos.

Utilizando o Google AI Studio com o modelo Gemini 2.5 Pro experimental, podemos criar um servidor MCP que integra um vector store da OpenAI, permitindo acesso a documentações específicas diretamente no Cursor.

Preparando o Terreno: Criando um Vector Store

Antes de mergulharmos no código, precisamos preparar nosso vector store que servirá como base de conhecimento para nosso servidor MCP. Neste exemplo, usaremos documentação do Three.js, uma popular biblioteca JavaScript para criação de gráficos 3D.

Passo a Passo para Criar um Vector Store na OpenAI

1. Acesse o dashboard da OpenAI e navegue até a seção “Storage”
2. Clique em “Create” e dê um nome ao seu vector store (ex: “3js_docs”)
3. Clique em “Add Files” e faça upload dos arquivos da documentação
4. Configure as opções avançadas:
   • Tamanho do chunk: 2000
   • Overlap: 400
5. Finalize o processo e guarde o ID do vector store para uso posterior

A criação do vector store é rápida e, uma vez concluída, você terá um ID único que será utilizado para acessar essa base de conhecimento a partir do seu servidor MCP.

Construindo o Servidor MCP em TypeScript

Agora que temos nossa base de conhecimento pronta, vamos criar o servidor MCP que conectará o Cursor a esse vector store. Siga os passos abaixo para configurar tudo corretamente:

Iniciando o Projeto

Primeiro, precisamos configurar a estrutura básica do nosso projeto:

1. Crie um novo diretório para o projeto e abra-o no Cursor
2. Inicialize o projeto Node.js com: npm init -y
3. Instale as dependências necessárias:

   npm install @cursor/mcp-server-sdk openai dotenv typescript @types/node --save

Estrutura de Arquivos

Seu projeto deve seguir esta estrutura de arquivos:

• src/
  • index.ts
  • types.ts
• .env
• config.json
• .gitignore
• package.json
• tsconfig.json

Configurando os Arquivos

Vamos configurar cada arquivo necessário para nosso servidor MCP:

1. .env – Para armazenar suas credenciais:

OPENAI_API_KEY=sua_chave_api_aqui
VECTOR_STORE_ID=seu_vector_store_id_aqui

2. .gitignore – Para evitar commits de arquivos sensíveis:

node_modules/
.env
build/

3. config.json – Configuração básica do servidor:

{
  "name": "OpenAI File Search",
  "version": "1.0.0",
  "description": "Query OpenAI file search vector store for relevant context"
}

4. types.ts – Definições de tipos para o projeto:

export interface FileSearchParams {
  query: string;
  maxChunks?: number;
}

export interface FileSearchResult {
  chunks: string[];
  metadata?: {
    source: string;
    score: number;
  }[];
}

5. index.ts – O coração do nosso servidor MCP:

import { MCPServer } from '@cursor/mcp-server-sdk';
import { FileSearchParams, FileSearchResult } from './types';
import OpenAI from 'openai';
import * as dotenv from 'dotenv';

dotenv.config();

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const vectorStoreId = process.env.VECTOR_STORE_ID;

if (!process.env.OPENAI_API_KEY || !vectorStoreId) {
  throw new Error('OPENAI_API_KEY and VECTOR_STORE_ID must be set in .env file');
}

const server = new MCPServer();

server.addTool({
  name: '3js_docs_search',
  description: 'Search the Three.js documentation for relevant information',
  parameters: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'The search query to find information in the Three.js documentation'
      },
      maxChunks: {
        type: 'number',
        description: 'Maximum number of chunks to return',
        default: 5
      }
    },
    required: ['query']
  },
  handler: async (params: FileSearchParams): Promise => {
    try {
      const { query, maxChunks = 5 } = params;
      
      const response = await openai.fileSearch.create({
        file_search_id: vectorStoreId,
        query,
        max_chunks: maxChunks,
      });

      return {
        chunks: response.chunks.map(chunk => chunk.text),
        metadata: response.chunks.map(chunk => ({
          source: chunk.source || 'unknown',
          score: chunk.score
        }))
      };
    } catch (error) {
      console.error('Error searching files:', error);
      throw error;
    }
  }
});

server.start();
console.log('MCP Server started successfully');

Compilação e Configuração Final

Agora precisamos compilar e configurar nosso servidor para que o Cursor possa reconhecê-lo:

1. Adicione scripts ao package.json:

   "scripts": {
     "build": "tsc",
     "start": "node build/index.js"
   }
           

2. Configure o tsconfig.json:

   {
     "compilerOptions": {
       "target": "ES2020",
       "module": "CommonJS",
       "outDir": "./build",
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true,
       "forceConsistentCasingInFileNames": true
     },
     "include": ["src/**/*"]
   }
           

3. Compile o projeto:

   npm run build

4. Crie um link NPM para o projeto:

   npm link

Conectando o Servidor MCP ao Cursor

O último passo é configurar o Cursor para reconhecer e utilizar nosso servidor MCP:

1. Crie um diretório .cursor na raiz do seu projeto
2. Dentro deste diretório, crie um arquivo mcp.json com o seguinte conteúdo:

   {
     "servers": [
       {
         "name": "3js_docs_search",
         "entrypoint": "./build/index.js",
         "env": {
           "OPENAI_API_KEY": "sua_chave_api_aqui",
           "VECTOR_STORE_ID": "seu_vector_store_id_aqui"
         }
       }
     ]
   }
           

3. Reinicie o Cursor
4. Acesse as configurações do Cursor e ative a opção MCP

Pronto! Agora você tem um servidor MCP completamente funcional que permite consultar a documentação do Three.js diretamente do seu ambiente de desenvolvimento.

Testando o Servidor MCP

Para testar se tudo está funcionando corretamente, abra o chat do Cursor e faça uma pergunta sobre o Three.js, como “Como criar fog em Three.js?”. O Cursor utilizará seu servidor MCP para buscar informações relevantes na documentação e fornecer uma resposta detalhada com referências diretas à documentação oficial.

Este fluxo de trabalho é extremamente valioso, pois:

• Elimina a necessidade de alternar entre a IDE e a documentação
• Fornece informações atualizadas, já que você pode atualizar seu vector store
• Melhora a precisão das respostas do assistente de IA ao fornecer contexto específico
• Acelera seu processo de desenvolvimento com informações relevantes e imediatas

Ampliando as Possibilidades

O exemplo que construímos utiliza a documentação do Three.js, mas você pode adaptar esta abordagem para qualquer biblioteca ou framework que seja relevante para seus projetos. Basta criar um vector store com a documentação desejada e ajustar o servidor MCP de acordo.

Algumas ideias de aplicações incluem:

• Documentação de APIs específicas da sua empresa
• Guias de estilo e padrões de código internos
• Documentação técnica de frameworks como React, Vue, Angular, etc.
• Tutoriais e exemplos de código relevantes para seu domínio

Experimente hoje mesmo! Configure seu próprio servidor MCP com vector store e transforme sua experiência de desenvolvimento com acesso instantâneo à documentação relevante diretamente no Cursor.

Dê o Próximo Passo com Este Conhecimento

Agora que você domina a criação de servidores MCP com vector stores, explore ainda mais esse potencial! Experimente criar vector stores para diferentes bibliotecas e frameworks relevantes para seus projetos. Compartilhe suas configurações com sua equipe para melhorar a produtividade coletiva.

Lembre-se que a integração entre IDEs inteligentes como o Cursor e bases de conhecimento personalizadas representa o futuro do desenvolvimento de software. Ao adotar essas ferramentas agora, você se posiciona na vanguarda da produtividade e inovação.

Pronto para experimentar? Comece hoje mesmo criando seu próprio servidor MCP e veja como isso pode transformar seu fluxo de trabalho de desenvolvimento!

Perguntas Frequentes