Contextual MCP Server

Um servidor para Geração Aumentada por Recuperação (RAG) usando a plataforma Contextual AI.

GitHub
21
Experimente este MCPPatrocinado

Documentação

Servidor Contextual MCP

Um servidor Model Context Protocol (MCP) que fornece capacidades de RAG (Geração Aumentada por Recuperação) usando Contextual AI. Este servidor integra-se com uma variedade de clientes MCP. Ele oferece flexibilidade para você decidir quais funcionalidades disponibilizar no servidor. Neste readme, mostraremos a integração com o IDE Cursor e o Claude Desktop.

A Contextual AI agora oferece um servidor hospedado dentro da plataforma, disponível em: https://mcp.app.contextual.ai/mcp/
Após conectar-se ao servidor, você pode usar as ferramentas, como consulta, fornecidas pelo servidor MCP da plataforma.
Para um passo a passo completo, consulte o guia do usuário do MCP.

Visão Geral

Um servidor MCP atua como uma ponte entre interfaces de IA (IDE Cursor ou Claude Desktop) e um agente especializado da Contextual AI. Ele permite:

  1. Processamento de Consultas: Direcione suas perguntas específicas de domínio para um agente dedicado da Contextual AI
  2. Recuperação Inteligente: Pesquisa informações abrangentes na sua base de conhecimento
  3. Respostas Contextuais: Gera respostas que são:
  • Fundamentadas na documentação de origem
  • Incluem citações e atribuições
  • Mantêm o contexto da conversa

Fluxo de Integração

Cursor/Claude Desktop → MCP Server → Contextual AI RAG Agent
        ↑                  ↓             ↓                         
        └──────────────────┴─────────────┴─────────────── Response with citations

Pré-requisitos

  • Python 3.10 ou superior
  • IDE Cursor e/ou Claude Desktop
  • Chave de API da Contextual AI
  • Ambiente compatível com MCP

Instalação

  1. Clone o repositório:
git clone https://github.com/ContextualAI/contextual-mcp-server.git
cd contextual-mcp-server
  1. Crie e ative um ambiente virtual:
python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
  1. Instale as dependências:
pip install -e .

Configuração

Configurar o Servidor MCP

O servidor requer modificações nas configurações ou no uso. Por exemplo, o servidor single_agent deve ser personalizado com um docstring apropriado para o seu Agente RAG.

O docstring da sua ferramenta de consulta é crítico, pois ajuda o cliente MCP a entender quando rotear perguntas para o seu agente RAG. Torne-o específico para o seu domínio de conhecimento. Aqui está um exemplo:

A research tool focused on financial data on the largest US firms

ou

A research tool focused on technical documents for Omaha semiconductors

O servidor também requer as seguintes configurações do seu Agente RAG:

  • API_KEY: Sua chave de API da Contextual AI
  • AGENT_ID: Seu ID de agente da Contextual AI

Se você quiser armazenar esses arquivos no arquivo .env, pode especificá-los da seguinte forma:

cat > .env << EOF
API_KEY=key...
AGENT_ID=...
EOF

O repositório também contém servidores MCP mais avançados para sistemas multi-agente ou um document-agent.

Integração com Interface de IA

Este servidor MCP pode ser integrado com uma variedade de clientes. Para usar com o IDE Cursor ou Claude Desktop, crie ou modifique o arquivo de configuração MCP no local apropriado:

  1. Primeiro, encontre o caminho para a sua instalação do uv:
UV_PATH=$(which uv)
echo $UV_PATH
# Example output: /Users/username/miniconda3/bin/uv
  1. Crie o arquivo de configuração usando o caminho completo da etapa 1:
cat > mcp.json << EOF
{
 "mcpServers": {
   "ContextualAI-TechDocs": {
     "command": "$UV_PATH", # make sure this is set properly
     "args": [
       "--directory",
       "\${workspaceFolder}",  # Will be replaced with your project path
       "run",
       "multi-agent/server.py"
     ]
   }
 }
}
EOF
  1. Mova para o local correto da pasta, veja as opções abaixo:
mkdir -p .cursor/
mv mcp.json .cursor/

Locais de configuração:

  • Para Cursor:
  • Específico do projeto: .cursor/mcp.json no diretório do seu projeto
  • Global: ~/.cursor/mcp.json para acesso em todo o sistema
  • Para Claude Desktop:
  • Use o mesmo formato de arquivo de configuração no diretório de configuração apropriado do Claude Desktop

Configuração do Ambiente

Este projeto usa uv para gerenciamento de dependências, que fornece instalação de pacotes Python mais rápida e confiável.

Uso

O servidor fornece capacidades de RAG da Contextual AI usando o SDK Python, que disponibiliza uma variedade de comandos acessíveis a partir de clientes MCP, como IDE Cursor e Claude Desktop. O servidor atual foca no uso do comando de consulta do SDK Python da Contextual AI, no entanto, você pode estendê-lo para suportar outros recursos, como listar todos os agentes, atualizar configurações de recuperação, atualizar prompts, extrair recuperações ou baixar métricas.

Exemplo de Uso

# In Cursor, you might ask:
"Show me the code for initiating the RF345 microchip?"

# The MCP client will:
1. Determine if this should be routed to the MCP Server

# Then the MCP server will:
1. Route the query to the Contextual AI agent
2. Retrieve relevant documentation
3. Generate a response with specific citations
4. Return the formatted answer to Cursor

Principais Benefícios

  1. Respostas Precisas: Todas as respostas são fundamentadas na sua documentação
  2. Atribuição de Fontes: Cada resposta inclui referências aos documentos de origem
  3. Consciência de Contexto: O sistema mantém o contexto da conversa para perguntas de acompanhamento
  4. Atualizações em Tempo Real: As respostas refletem a documentação mais recente no seu armazenamento de dados

Desenvolvimento

Modificando o Servidor

Para adicionar novas capacidades:

  1. Adicione novas ferramentas criando funções adicionais decoradas com @mcp.tool()
  2. Defina os parâmetros da ferramenta usando dicas de tipo do Python
  3. Forneça um docstring claro descrevendo a funcionalidade da ferramenta

Exemplo:

@mcp.tool()
def new_tool(param: str) -> str:
   """Description of what the tool does"""
   # Implementation
   return result

Limitações

  • O servidor é executado localmente e pode não funcionar em ambientes de desenvolvimento remotos
  • As respostas das ferramentas estão sujeitas aos limites e cotas da API da Contextual AI
  • Atualmente, suporta apenas o modo de transporte stdio

Para todas as capacidades da Contextual AI, consulte a documentação oficial.