mcp-server-python

MCP server em Python com tools customizadas para agentes IA — knowledge base local, contexto de negócio e sumarização de texto.

---

O que é MCP?

MCP (Model Context Protocol) é um protocolo aberto criado pela Anthropic que permite que agentes IA (como o Claude) se conectem a servidores externos para acessar dados, executar ações e usar ferramentas customizadas.

Com um MCP server, você pode:

• Dar ao Claude acesso à sua base de conhecimento interna
• Expor dados de negócio sem precisar colocá-los no prompt manualmente
• Criar pipelines de processamento de texto reutilizáveis
• Integrar qualquer sistema externo como uma "tool" para o agente

Este servidor expõe 3 tools prontas:

Tool	O que faz
search_knowledge_base	Busca documentos relevantes numa SQLite local via cosine similarity
summarize_text	Formata um prompt de sumarização (sem chamar API — retorna o prompt pronto)
get_business_context	Retorna contexto de negócio de um JSON local

---

Instalação

Pré-requisitos

• Python 3.12+
• pip

Passos

# Clone o repositório
git clone https://github.com/dimitrearaujo/mcp-server-python.git
cd mcp-server-python

# Crie e ative o ambiente virtual
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# ou
.venv\Scripts\activate  # Windows

# Instale as dependências
pip install -r requirements.txt

# Configure as variáveis de ambiente
cp .env.example .env
# Edite o .env conforme necessário

Configuração

Edite o arquivo .env:

BUSINESS_CONTEXT_PATH=./business_context.json
KB_DATABASE_PATH=./data/knowledge_base.db
KB_MAX_RESULTS=5

Edite o business_context.json com os dados da sua empresa.

---

Como rodar

python server.py

O servidor inicia via stdio e aguarda chamadas de tools. A saída de log vai para stderr.

---

Integração com Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-python": {
      "command": "python",
      "args": ["/caminho/para/mcp-server-python/server.py"],
      "env": {
        "BUSINESS_CONTEXT_PATH": "/caminho/para/mcp-server-python/business_context.json",
        "KB_DATABASE_PATH": "/caminho/para/mcp-server-python/data/knowledge_base.db"
      }
    }
  }
}

Localização do arquivo de configuração:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Após reiniciar o Claude Desktop, as tools aparecerão disponíveis no chat.

---

Populando a Knowledge Base

Use o Python interativo ou um script para inserir documentos:

from mcp_server.knowledge_base import KnowledgeBase

kb = KnowledgeBase(db_path="./data/knowledge_base.db")

# Inserir documentos
kb.insert(
    title="Política de Atendimento",
    content="Atendemos de segunda a sexta, das 8h às 18h. Urgências via WhatsApp.",
    category="atendimento"
)

kb.insert(
    title="Tabela de Preços",
    content="Consulta simples: R$ 150. Consulta especializada: R$ 250. Retorno em 30 dias: gratuito.",
    category="precos"
)

# Buscar
results = kb.search("qual o preço da consulta?")
for r in results:
    print(f"[{r['score']:.2f}] {r['title']}: {r['content'][:80]}...")

---

Como adicionar novas tools

1. Defina a tool em mcp_server/tools.py, adicionando um item a TOOL_DEFINITIONS:

{
    "name": "minha_nova_tool",
    "description": "Descrição clara do que a tool faz.",
    "input_schema": {
        "type": "object",
        "properties": {
            "parametro": {"type": "string", "description": "..."},
        },
        "required": ["parametro"],
    },
}

2. Implemente o handler assíncrono:

async def handle_minha_nova_tool(arguments: Dict[str, Any]) -> List[TextContent]:
    resultado = faz_algo(arguments["parametro"])
    return [TextContent(type="text", text=json.dumps(resultado, ensure_ascii=False))]

3. Registre o handler no dicionário TOOL_HANDLERS:

TOOL_HANDLERS = {
    # ... tools existentes ...
    "minha_nova_tool": handle_minha_nova_tool,
}

4. Pronto. A tool já aparece automaticamente via list_tools.

---

Estrutura do projeto

mcp-server-python/
├── .env.example              # Variáveis de ambiente necessárias
├── .gitignore
├── .github/workflows/ci.yml  # CI: syntax check + unit tests
├── README.md
├── requirements.txt
├── server.py                 # Entry point — inicia o MCP server via stdio
├── mcp_server/
│   ├── __init__.py
│   ├── tools.py              # Definição e registro das 3 tools
│   ├── knowledge_base.py     # SQLite + busca vetorial TF cosine
│   ├── context.py            # Carrega business_context.json
│   └── prompts.py            # Templates de prompt
├── business_context.json     # Contexto de negócio (edite com seus dados)
└── data/                     # Pasta para arquivos da KB (SQLite)
    └── .gitkeep

---

Tecnologias

• MCP SDK — protocolo de comunicação com agentes IA
• SQLite — armazenamento local da knowledge base (sem servidor externo)
• TF Cosine Similarity — busca vetorial simples sem embeddings externos
• python-dotenv — gerenciamento de variáveis de ambiente

---

Desenvolvido por

CD Tech — Automação e Agentes IA para Pequenos Negócios Fortaleza, CE — Brasil cd-tech-lp.pages.dev

---

🇺🇸 English

mcp-server-python

Python MCP server with custom tools for AI agents — local knowledge base, business context and text summarization.

---

What is MCP?

MCP (Model Context Protocol) is an open protocol created by Anthropic that lets AI agents (like Claude) connect to external servers to access data, execute actions and use custom tools.

With an MCP server, you can:

• Give Claude access to your internal knowledge base
• Expose business data without having to paste it into the prompt manually
• Build reusable text-processing pipelines
• Integrate any external system as a "tool" for the agent

This server exposes 3 ready-to-use tools:

Tool	What it does
search_knowledge_base	Searches relevant documents in a local SQLite via cosine similarity
summarize_text	Formats a summarization prompt (no API call — returns the ready prompt)
get_business_context	Returns business context from a local JSON file

---

Installation

Prerequisites

• Python 3.12+
• pip

Steps

# Clone the repository
git clone https://github.com/dimitrearaujo/mcp-server-python.git
cd mcp-server-python

# Create and activate the virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit .env as needed

Configuration

Edit the .env file:

BUSINESS_CONTEXT_PATH=./business_context.json
KB_DATABASE_PATH=./data/knowledge_base.db
KB_MAX_RESULTS=5

Edit business_context.json with your company's data.

---

How to run

python server.py

The server starts via stdio and waits for tool calls. Log output goes to stderr.

---

Claude Desktop integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-python": {
      "command": "python",
      "args": ["/path/to/mcp-server-python/server.py"],
      "env": {
        "BUSINESS_CONTEXT_PATH": "/path/to/mcp-server-python/business_context.json",
        "KB_DATABASE_PATH": "/path/to/mcp-server-python/data/knowledge_base.db"
      }
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

After restarting Claude Desktop, the tools will show up as available in the chat.

---

Populating the Knowledge Base

Use interactive Python or a script to insert documents:

from mcp_server.knowledge_base import KnowledgeBase

kb = KnowledgeBase(db_path="./data/knowledge_base.db")

# Insert documents
kb.insert(
    title="Support Policy",
    content="We're open Monday to Friday, 8am to 6pm. Urgent requests via WhatsApp.",
    category="support"
)

kb.insert(
    title="Price Table",
    content="Basic consultation: $30. Specialized consultation: $50. Follow-up within 30 days: free.",
    category="pricing"
)

# Search
results = kb.search("what's the price of a consultation?")
for r in results:
    print(f"[{r['score']:.2f}] {r['title']}: {r['content'][:80]}...")

---

How to add new tools

1. Define the tool in mcp_server/tools.py, adding an entry to TOOL_DEFINITIONS:

{
    "name": "my_new_tool",
    "description": "Clear description of what the tool does.",
    "input_schema": {
        "type": "object",
        "properties": {
            "parameter": {"type": "string", "description": "..."},
        },
        "required": ["parameter"],
    },
}

2. Implement the async handler:

async def handle_my_new_tool(arguments: Dict[str, Any]) -> List[TextContent]:
    result = do_something(arguments["parameter"])
    return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False))]

3. Register the handler in the TOOL_HANDLERS dict:

TOOL_HANDLERS = {
    # ... existing tools ...
    "my_new_tool": handle_my_new_tool,
}

4. Done. The tool automatically shows up via list_tools.

---

Project structure

mcp-server-python/
├── .env.example              # Required environment variables
├── .gitignore
├── .github/workflows/ci.yml  # CI: syntax check + unit tests
├── README.md
├── requirements.txt
├── server.py                 # Entry point — starts the MCP server via stdio
├── mcp_server/
│   ├── __init__.py
│   ├── tools.py              # Definition and registration of the 3 tools
│   ├── knowledge_base.py     # SQLite + TF cosine vector search
│   ├── context.py            # Loads business_context.json
│   └── prompts.py            # Prompt templates
├── business_context.json     # Business context (edit with your data)
└── data/                     # Folder for KB files (SQLite)
    └── .gitkeep

---

Technologies

• MCP SDK — communication protocol with AI agents
• SQLite — local knowledge base storage (no external server)
• TF Cosine Similarity — simple vector search without external embeddings
• python-dotenv — environment variable management

---

Developed by

CD Tech — AI Automation & Agents for Small Businesses Fortaleza, Brazil cd-tech-lp.pages.dev

---

← Back to profile