Skip to main content
Glama
deenesjakoptruzh
Gagocode

mcp-server

by Gagocode
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

MCP Server — AI 工具服务器

这是一个教育项目，旨在演示 AI 如何连接到服务器以在操作系统上执行实际操作。

什么是这个项目？

本项目模拟了一个 MCP Server（模型上下文协议服务器）——一个公开 工具 (tools) 的 HTTP 服务器，人工智能可以远程调用这些工具。

核心思想很简单：AI 不会直接在操作系统上执行命令。相反，它会向此服务器发送 HTTP 请求，要求执行某个工具。服务器接收请求、执行操作并返回结果。

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

Related MCP server: Shell Server

项目目标

  • 演示应用于 AI 的 客户端-服务器 架构

  • 展示如何 动态注册和选择 工具

  • 作为大型项目的 学习基础

  • 易于理解、修改和演示

使用的技术栈

技术

用途

Node.js

JavaScript 运行时

Express.js

HTTP 框架

fs, os, path

Node 原生模块

child_process

系统命令执行

文件夹结构

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

如何安装

先决条件： 已安装 Node.js（建议版本 18 或更高）。

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

# Instale as dependências
npm install

如何运行

# Modo normal
npm start

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

服务器默认将在 3000 端口启动。

若要使用其他端口：

PORT=8080 npm start

如何验证是否正常工作

在浏览器中访问或通过 curl 访问：

curl http://localhost:3000/health

预期响应：

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

如何使用 — API

有两个主要端点：一个用于列出工具，另一个用于执行工具。

列出可用工具

返回服务器中注册的所有工具及其 完整模式 (schemas)（描述和参数）。这种格式便于与 AI（工具调用）集成。

GET http://localhost:3000/tools

响应：

{
  "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"]
      }
    }
  ]
}

执行工具

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

请求格式

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

可用工具

get_ip

返回机器的本地 IP。

请求：

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

get_hostname

返回机器的主机名、平台和架构。

请求：

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

list_files

列出路径下的文件和目录。如果省略 path，则使用当前进程目录。

请求：

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

create_file

在服务器根目录的 /files 文件夹内创建一个文件。该文件夹作为沙箱，用于组织生成的文件。

请求：

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

ping_host

对主机或 IP 执行 ping 操作并返回结果。 安全性： 主机名仅允许字母数字、点和连字符，以防止命令注入。

请求：

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

使用 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"}}'

完整流程 — AI → MCP → 系统

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

未来可能的改进

  • 添加 API Key 身份验证

  • 实现调用日志（谁在何时调用了哪个工具）

  • 添加对流式结果的 WebSocket 支持

  • 与本地 AI 模型集成（Ollama, LM Studio）

  • 添加新工具：CPU/内存读取、脚本执行等

  • 创建一个模拟 AI 调用工具的示例客户端

安全注意事项

本项目仅供 教育 使用。若要在生产环境中使用，需要：

  • 路由身份验证

  • list_files 和 create_file 的路径白名单

  • 速率限制

  • 更健壮的输入清理

  • HTTPS

项目开发仅用于学术和演示目的。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Combined MCP Server

    SMH01-MOD-NEXT
    A
    license
    Not graded
    quality
    C
    maintenance
    A self-hosted MCP server that gives AI agents controlled access to a machine: filesystem, shell, background processes, git, web fetching and persistent key-value memory.
    GPL 3.0