NodeJS Implementation of an MCP Server (mcp-agent-orchestrator)

This repository showcases an AI agent framework leveraging the Model Context Protocol (MCP) for secure and structured access to external data endpoints.

Repository Contents:

• A fully operational MCP server instance featuring REST interfaces for managing user records and message broadcasts.
• An accompanying MCP client module designed to consume these structured resources via the protocol.
• Comprehensive, runnable examples demonstrating resource access via command line (terminal), direct REST calls, or integration within the Cursor IDE environment.

Exposed Functionality

The MCP server exposes the following service endpoints:

User Management Resources

• api://users: Retrieves an exhaustive enumeration of all registered system subjects.
• Returns structured data detailing attributes such as Subject ID, full designation, contact telephone number, and associated communication thread identifier.
• Data Serialization Format: JSON

• Illustrative Response Payload:

  { "content": [ { "id": 1, "phoneNumber": "553496341404", "name": "Moisés Paschoalick", "threadId": "thread_bZEPVYVBvHxY9Ok6WqR63M2D" }, // ... additional user objects ], "pageable": { / ... paging metadata ... / }, "last": true, "totalPages": 1, "totalElements": 3, "first": true, "size": 12, "number": 0, "sort": { / ... sort metadata ... / }, "numberOfElements": 3, "empty": false }

System Messaging Resources

• hello://world: Delivers a foundational greeting message.
• Serialization Format: Plain text (Content-Type: text/plain)
• Example Output: "Hello, World! This is my first MCP resource."

Deployment Instructions for Cursor Integration

Ensure you have the Cursor application installed and a functional Node Package Manager (npm) environment accessible.

Method 1: Direct CLI Provisioning

Execute the following invocation in your terminal:

bash npx -y @smithery/cli@latest install @wonderwhy-er/desktop-commander --client cursor --key dda23bec-caa6-4487-a1e9-eb74e22e33eb

Note: The provided key is purely illustrative; substitute it with your valid authorization token.

Apply a restart to the Cursor application to finalize setup.

Method 2: Manual Configuration File Modification

Inject the requisite configuration block into your mcp.json manifest file:

Unix-like Systems (macOS/Linux):

Location example: ~/.config/cursor.json

{ "mcpServers": { "desktop-commander": { "command": "npx", "args": [ "-y", "@smithery/cli@latest", "run", "@wonderwhy-er/desktop-commander", "--key", "dda23bec-caa6-4487-a1e9-eb74e22e33eb" ] } } }

Windows Operating System:

{ "mcpServers": { "desktop-commander": { "command": "cmd", "args": [ "/c", "npx", "-y", "@smithery/cli@latest", "run", "@wonderwhy-er/desktop-commander", "--key", "dda23bec-caa6-4487-a1e9-eb74e22e33eb" ] } } }

Restart Cursor to activate the manually configured server connection.

Method 3: Local Source Code Checkout and Build

Clone the repository and execute the local setup sequence:

bash git clone https://github.com/moises-paschoalick/ai-agent-with-mcp.git cd ai-agent-with-mcp npm run setup

The setup script performs the following automated actions: - Fetches and installs necessary project dependencies. - Compiles the TypeScript source files into executable JavaScript. - Orchestrates the Cursor tooling configuration. - Optionally registers the MCP server definitions within the Cursor environment settings.

Restart Cursor to ensure the local build is recognized.

Usage Protocols

Utilizing the MCP Client Module

The project includes a dedicated client utility for programmatic interaction:

typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() { const client = new Client({ name: "hello-mcp-client", version: "1.0.0" }); const transport = new StdioClientTransport({ command: "node", args: ["build/index.js"] });

try { await client.connect(transport);

// Enumerating available endpoints
const resources = await client.listResources();
console.log("Exposed Resources:", resources);

// Fetching the user directory resource
const content = await client.readResource({ uri: "api://users" });
console.log("\nUser Registry Data:", content);

} catch (error) { console.error("Client execution failure:", error); } }

main().catch(console.error);

Direct HTTP Endpoint Access

Resources are also directly reachable via the exposed REST API interface:

bash

Retrieve the complete subject roster

curl http://3.238.149.189:8080/users

Operational Commands

bash

Install project dependencies

npm install

Compile the source code base

npm run build

Initiate the production server instance

npm start

Launch the server in debugging/hot-reloading mode

npm run dev

Prerequisites

• A compatible version of the Node.js runtime (supporting AbortController functionality).
• TypeScript compiler environment.
• The official @modelcontextprotocol/sdk library dependency.