How do I use mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server what's my IP address?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Server — Servidor de Ferramentas para IA

Projeto educacional que demonstra como uma IA pode se conectar a um servidor para executar ações reais em um sistema operacional.

O que é este projeto?

Este projeto simula um MCP Server (Model Context Protocol Server) — um servidor HTTP que expõe ferramentas (tools) que uma Inteligência Artificial pode chamar remotamente.

A ideia central é simples: a IA não executa comandos no sistema operacional diretamente. Em vez disso, ela envia uma requisição HTTP para este servidor pedindo que uma tool seja executada. O servidor recebe, executa e devolve o resultado.

IA  →  POST /tool { "tool": "get_ip" }  →  MCP Server  →  Sistema Operacional
IA  ←  { "success": true, "result": { "ips": [...] } }  ←  MCP Server

Objetivo do projeto

Demonstrar arquitetura cliente-servidor aplicada à IA
Mostrar como ferramentas podem ser registradas e selecionadas dinamicamente
Servir como base de aprendizado para projetos maiores
Ser fácil de entender, modificar e apresentar

Stack utilizada

Tecnologia	Uso
Node.js	Runtime JavaScript
Express.js	Framework HTTP
fs, os, path	Módulos nativos do Node
child_process	Execução de comandos do sistema

Estrutura de pastas

mcp-server/
│
├── src/
│   ├── server.js              ← Ponto de entrada — inicia o servidor
│   ├── routes/
│   │   └── tools.routes.js    ← Define as rotas HTTP
│   ├── controllers/
│   │   └── tools.controller.js ← Valida o input e chama o serviço
│   ├── services/
│   │   └── tools.service.js   ← Registry de tools + lógica de seleção
│   ├── tools/
│   │   ├── getIp.js           ← Tool: retorna o IP da máquina
│   │   ├── getHostname.js     ← Tool: retorna o hostname
│   │   ├── listFiles.js       ← Tool: lista arquivos de um diretório
│   │   ├── createFile.js      ← Tool: cria um arquivo
│   │   └── pingHost.js        ← Tool: faz ping em um host
│   └── utils/
│       └── response.js        ← Padroniza respostas JSON
│
├── docs/
│   ├── README.md              ← Este arquivo
│   └── AI_CONTEXT.md          ← Contexto arquitetural para IAs
│
├── package.json
└── .gitignore

Como instalar

Pré-requisito: Node.js instalado (versão 18 ou superior recomendada).

# Clone ou copie o projeto para sua máquina
cd mcp-server

# Instale as dependências
npm install

Como executar

# Modo normal
npm start

# Modo desenvolvimento (reinicia ao salvar arquivos — Node 18+)
npm run dev

O servidor irá iniciar na porta 3000 por padrão.

Para usar outra porta:

PORT=8080 npm start

Como verificar que está funcionando

Acesse no navegador ou via curl:

curl http://localhost:3000/health

Resposta esperada:

{ "status": "ok", "message": "MCP Server rodando" }

Como usar — API

Existem dois endpoints principais: um para listar ferramentas e outro para executá-las.

Listar ferramentas disponíveis

Retorna todas as ferramentas registradas no servidor com seus schemas completos (descrição e parâmetros). Este formato facilita a integração com IAs (Tool Calling).

GET http://localhost:3000/tools

Resposta:

{
  "success": true,
  "result": [
    {
      "name": "create_file",
      "description": "Cria um arquivo dentro da pasta /files.",
      "parameters": {
        "type": "object",
        "properties": {
          "filename": { "type": "string", "description": "..." },
          "content": { "type": "string", "description": "..." }
        },
        "required": ["filename"]
      }
    }
  ]
}

Executar uma ferramenta

POST http://localhost:3000/tool
Content-Type: application/json

Formato da requisição

{
  "tool": "nome_da_tool",
  "args": {
    "parametro": "valor"
  }
}

Tools disponíveis

`get_ip`

Retorna os IPs locais da máquina.

Request:

{ "tool": "get_ip", "args": {} }

`get_hostname`

Retorna o hostname, plataforma e arquitetura da máquina.

Request:

{ "tool": "get_hostname", "args": {} }

`list_files`

Lista arquivos e diretórios de um caminho. Se path for omitido, usa o diretório atual do processo.

Request:

{ "tool": "list_files", "args": { "path": "/home/user" } }

`create_file`

Cria um arquivo dentro da pasta /files na raiz do servidor. Essa pasta funciona como um sandbox para organizar os arquivos gerados.

Request:

{
  "tool": "create_file",
  "args": {
    "filename": "teste.txt",
    "content": "Olá, MCP!"
  }
}

`ping_host`

Faz ping em um host ou IP e retorna o resultado. Segurança: Apenas caracteres alfanuméricos, pontos e hifens são permitidos no host para evitar injeção de comandos.

Request:

{ "tool": "ping_host", "args": { "host": "8.8.8.8" } }

Testando com curl

# get_ip
curl -X POST http://localhost:3000/tool \
  -H "Content-Type: application/json" \
  -d '{"tool": "get_ip", "args": {}}'

# list_files
curl -X POST http://localhost:3000/tool \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_files", "args": {"path": "/tmp"}}'

# create_file
curl -X POST http://localhost:3000/tool \
  -H "Content-Type: application/json" \
  -d '{"tool": "create_file", "args": {"filename": "ola.txt", "content": "Olá mundo!"}}'

# ping_host
curl -X POST http://localhost:3000/tool \
  -H "Content-Type: application/json" \
  -d '{"tool": "ping_host", "args": {"host": "8.8.8.8"}}'

Fluxo completo — IA → MCP → Sistema

1. IA decide que precisa saber o IP da máquina
2. IA envia: POST /tool { "tool": "get_ip", "args": {} }
3. Express recebe a requisição
4. Route encaminha para o Controller
5. Controller valida o body e chama o Service
6. Service consulta o Registry e encontra a função getIp
7. getIp() usa o módulo "os" para ler as interfaces de rede
8. Resultado sobe de volta: getIp → Service → Controller → Response
9. IA recebe: { "success": true, "result": { "ips": [...] } }
10. IA usa o resultado para continuar sua tarefa

Possíveis melhorias futuras

Adicionar autenticação via API Key
Implementar log de chamadas (quem chamou qual tool e quando)
Adicionar suporte a WebSocket para resultados em streaming
Integrar com modelos de IA locais (Ollama, LM Studio)
Adicionar novas tools: leitura de CPU/memória, execução de scripts, etc.
Criar um cliente de exemplo que simula uma IA chamando as tools

Observações de segurança

Este projeto é educacional. Para uso em produção, seria necessário:

Autenticação nas rotas
Whitelist de caminhos para list_files e create_file
Rate limiting
Sanitização mais robusta de inputs
HTTPS

Projeto desenvolvido para fins acadêmicos e de demonstração.

mcp-server

MCP Server — Servidor de Ferramentas para IA

O que é este projeto?

Objetivo do projeto

Stack utilizada

Estrutura de pastas

Como instalar

Como executar

Como verificar que está funcionando

Como usar — API

Listar ferramentas disponíveis

Executar uma ferramenta

Formato da requisição

Tools disponíveis

`get_ip`

`get_hostname`

`list_files`

`create_file`

`ping_host`

Testando com curl

Fluxo completo — IA → MCP → Sistema

Possíveis melhorias futuras

Observações de segurança

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API