Skip to main content
Glama
deenesjakoptruzh
Gagocode

mcp-server

by Gagocode
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

MCP 서버 — AI용 도구 서버

AI가 운영 체제에서 실제 작업을 수행하기 위해 서버에 연결하는 방법을 보여주는 교육용 프로젝트입니다.

이 프로젝트란 무엇인가요?

이 프로젝트는 MCP 서버(Model Context Protocol 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

두 개의 주요 엔드포인트가 있습니다. 하나는 도구 목록을 나열하고, 다른 하나는 도구를 실행합니다.

사용 가능한 도구 나열

서버에 등록된 모든 도구를 전체 스키마(설명 및 매개변수)와 함께 반환합니다. 이 형식은 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에 핑을 보내고 결과를 반환합니다. 보안: 명령 주입을 방지하기 위해 호스트에는 영숫자, 점, 하이픈만 허용됩니다.

요청:

{ "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 키를 통한 인증 추가

  • 호출 로그 구현 (누가, 언제, 어떤 도구를 호출했는지)

  • 스트리밍 결과를 위한 WebSocket 지원 추가

  • 로컬 AI 모델(Ollama, LM Studio)과 통합

  • 새로운 도구 추가: CPU/메모리 읽기, 스크립트 실행 등

  • 도구를 호출하는 AI를 시뮬레이션하는 예제 클라이언트 생성

보안 참고 사항

이 프로젝트는 교육용입니다. 프로덕션 환경에서 사용하려면 다음이 필요합니다:

  • 경로 인증

  • list_files 및 create_file에 대한 경로 화이트리스트

  • 속도 제한(Rate limiting)

  • 더 강력한 입력값 정제(Sanitization)

  • 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