Skip to main content
Glama
deenesjakoptruzh
Gagocode

mcp-server

by Gagocode
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

MCP Server — AI用ツールサーバー

AIがサーバーに接続してオペレーティングシステム上で実際の操作を実行する方法を実演する教育プロジェクト。

このプロジェクトとは？

このプロジェクトは、MCP Server（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

主に2つのエンドポイントがあります。1つはツールを一覧表示するためのもの、もう1つはそれらを実行するためのものです。

利用可能なツールの一覧表示

サーバーに登録されているすべてのツールを、その完全なスキーマ（説明とパラメータ）とともに返します。この形式により、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キーによる認証の追加

  • 呼び出しログの実装（誰がどのツールをいつ呼び出したか）

  • ストリーミング結果のための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