MCPlex-AI v1.0

This document provides an introduction to MCPlex-AI v1.0, a system that integrates Google's Gemini large language model with external tools through a Model Context Protocol (MCP). Unlike typical chatbot frontends, MCPlex-AI runs entirely from the command line, giving users fine-grained control and a minimalistic interface to execute intelligent queries and trigger tool-based actions — all from a single terminal. The document covers the system's purpose, high-level architecture, key components, and interaction patterns. For detailed information about specific components, please refer to their respective sections:

Purpose

MCPlex-AI v1.0 is designed to enhance the capabilities of large language models (Google Gemini-2.0) by enabling them to interact with external tools and APIs. This allows the AI to:

1. Access real-time information (news, Wikipedia, etc.)
2. Perform specific actions (post to Twitter, search files)
3. Calculate results (truth tables, mathematical operations)
4. Retrieve data from external services (GitHub, OMDB)

System Architecture

The system follows a client-server architecture where the client handles user interaction and AI communication, while the server manages tool execution. MCPlex-AI consists of three primary components:

• MCP Client (client/index.js): Handles user chat with Google Gemini AI, sends tool execution requests to the server
• MCP Server (server/index.js): Manages tool registration and execution, handles client requests
• Tool System (server/tools.js): Collection of tools that extend the AI's capabilities

The diagram below illustrates the high-level architecture of the system:

Available Tools

Tool Name	Description	Source Location
print-menu	Prints available tools	server/tools.js (37-71)
news-by-topic	Fetches news headlines	server/tools.js (74-128)
twitter-X-post	Posts to Twitter/X	server/tools.js (156-177)
wikipedia-search	Searches Wikipedia	server/tools.js (180-225)
github-repo-info	Gets GitHub repo info	server/tools.js (228-268)
movie-ratings	Gets movie information	server/tools.js (271-354)
local-file-search	Searches local files	server/tools.js (356-522)
truth_table	Generates truth tables	server/tools.js (525-588)
define_word	Gets word definitions	server/tools.js (590-618)

Usage

1. Print Menu Tool

Name: print-menu Description: Prints what the MCP server can do with the available tools, provides descriptions of tools.

Input Parameters:

• title (string, optional): Optional title for the menu
• items (array of strings): List of tool descriptions to display
• Output: Formatted text displaying the menu items with numbering.

2. News by Topic Tool

Name: news-by-topic Description: Fetches recent news headlines for a given topic using Google News.

Input Parameters:

• topic (string): The topic to search news for (e.g., AI, economy, cricket)
• Output: Formatted text containing up to 5 recent news headlines with links.

Example Response:

Top News for "AI":

[1] Microsoft announces new AI features for Windows 11 Read more
[2] OpenAI unveils GPT-5 with improved reasoning capabilities Read more
[3] AI regulation bill passes in EU parliament Read more
[4] AI startup funding reaches record high in Q2 2023 Read more
[5] New research shows AI models becoming more energy efficient Read more

3. Adder Tool (First tool for basic testing)

Name: adder Description: Adds two numbers together.

Input Parameters:

• a (number): The first number
• b (number): The second number
• Output: Text containing the sum of the two numbers.

4. Twitter/X Post Tool

Name: twitter-X-post Description: Creates and posts a tweet on X (formerly Twitter).

Input Parameters:

• status (string): The content of the tweet
• Output: Confirmation text with the posted tweet ID.
• Note: Requires Twitter API configuration in server environment.

5. Wikipedia Search Tool

Name: wikipedia-search Description: Searches Wikipedia and returns the summary of the top result.

Input Parameters:

• query (string): The search term for Wikipedia
• Output: Title, summary extract, and link to the Wikipedia article.

Example Response:

Artificial Intelligence

Artificial intelligence (AI) is intelligence demonstrated by machines, as opposed to the natural intelligence displayed by animals including humans. AI research has been defined as the field of study of intelligent agents, which refers to any system that perceives its environment and takes actions that maximize its chance of achieving its goals.

Read more on Wikipedia

6. GitHub Repo Info Tool

Name: github-repo-info Description: Fetches information about a public GitHub repository.

Input Parameters:

• owner (string): GitHub username or organization
• repo (string): Repository name
• Output: Formatted text containing repository details, including stars, forks, and open issues.

Example Response:

📦 Repository Name: octocat/Hello-World

📝 Description: My first repository on GitHub!
⭐ Stars: 1337
🍴 Forks: 1234
🚩 Open Issues: 42
🔗 Repository Link: https://github.com/octocat/Hello-World

7. Movie Ratings Tool

Name: movie-ratings Description: Gets ratings and information for movies or TV shows from various sources.

Input Parameters:

• title (string): The title of the movie or TV show to search for
• year (number, optional): Release year to narrow down search results
• plot (enum: 'short' or 'full', default: 'short', optional): Length of plot summary
• Output: Comprehensive formatted information about the movie/show, including ratings from different sources, plot summary, and additional details.

Example Response:

🎬 The Matrix (1999)

Genre: Action, Sci-Fi
Director: Lana Wachowski, Lilly Wachowski
Starring: Keanu Reeves, Laurence Fishburne, Carrie-Anne Moss
Runtime: 136 min

⭐ RATINGS

IMDB: 8.7/10 ⭐⭐⭐⭐⭐⭐⭐⭐⭐ (1,780,994 votes)
Rotten Tomatoes: 88%
Metacritic: 73/100

PLOT: A computer hacker learns from mysterious rebels about the true nature of his reality and his role in the war against its controllers.

ADDITIONAL INFO

Rated: R
Released: 31 Mar 1999
Awards: Won 4 Oscars. 42 wins & 51 nominations total
Box Office: $171,479,930

View on IMDB

Note: Requires OMDB API key configuration in server environment.

8. Local File Search Tool

Name: local-file-search

Description: Finds files on the local system based on name, extension, or content.

Input Parameters:

• searchTerm (string): Term to search for in filenames or content
• directory (string, default: './'): Directory to search in
• fileType (enum: 'all', 'name', 'extension', 'content', default: 'all'): Type of search
• Output: Formatted text containing search results with file details including name, size, and last modified date.

Example Response:

File Search Results

Search term: "config"
Directory: ./src
Search type: all
Files scanned: 156
Matches found: 7

Filename                Size        Last Modified
────────────────────────────────────────────────────────────
 1) config.json         12.4 KB     2023-03-15 14:22:18
 2) app.config.js        8.7 KB     2023-03-14 10:15:46
 3) webpack.config.js   15.3 KB     2023-03-10 09:38:21
 4) test-config.json     2.1 KB     2023-03-09 16:45:32
 5) .env.config          1.2 KB     2023-03-08 11:23:57
 6) config-utils.js      5.9 KB     2023-03-05 19:12:08
 7) server-config.js     7.8 KB     2023-03-01 14:30:42

9. Truth Table Generator Tool

Name: truth_table Description: Generates the truth table of a boolean expression.

Input Parameters:

• expression (string): Boolean expression using variables like A, B, C and operators like &&, ||, !
• Output: Formatted truth table showing all possible combinations of variable values and the resulting expression evaluation.

Example Response:

Truth Table:
A | B | C | Result
--------------------
F   F   F |   F
F   F   T |   T
F   T   F |   F
F   T   T |   T
T   F   F |   F
T   F   T |   T
T   T   F |   T
T   T   T |   T

Sources: server/tools.js (525-588)

10. Define Word Tool

Name: define_word Description: Gets the definition and example usage of a word.

Input Parameters:

• word (string): Word to define
• Output: Definition and example usage of the specified word.

Example Response:

📖 Definition of serendipity: The occurrence and development of events by chance in a happy or beneficial way.
💡 Example: A fortunate stroke of serendipity came his way when he met his future wife on a flight.

Model Context Protocol (MCP)

The Model Context Protocol (MCP) is a standardized communication protocol that enables the MCPlex-AI system to connect large language models (LLMs) with external tools. This protocol serves as the foundation for interactions between the client application and the server component, allowing the Google Gemini AI model to discover, request, and utilize various tools to enhance its capabilities.

Communication Flow

The Model Context Protocol follows a request-response pattern but extends it with session management and streaming capabilities. The flow typically begins with session initialization, followed by tool discovery, and then tool invocation as needed by the AI.

Setup and Installation Guide

This section provides step-by-step instructions for setting up and installing the MCPlex-AI v1.0 system. It covers repository setup, configuring the client and server components, setting up necessary API keys, and running the system.

Prerequisites

Ensure the following are installed and available before installation:

• Node.js (v16 or higher)
• npm (v7 or higher)
• Access to the following external APIs:
  • Google Gemini API
  • Twitter/X API
  • OMDB API

Required API Keys

API	Purpose
Google Gemini	Connect to Gemini AI
Twitter API	Post tweets via AI agent
OMDB API	Fetch movie/TV ratings

Repository Setup

git clone https://github.com/Ecolash/MCPlex-AI-v1.0.git
cd MCPlex-AI-v1.0

Structure

MCPlex-AI-v1.0/
│
├── client/            # Client app, Gemini connection
│   ├── .env.example
│   ├── index.js
│   └── package.json
│
├── server/            # MCP server and tools
│   ├── .env.example
│   ├── server.js
│   ├── tools/
│   └── package.json
│
├── .gitignore
└── README.md

Server Setup

The server hosts the MCP controller and tool modules.

cd server
npm install

Server Environment Configuration

1. Copy .env.example to .env
2. Add the required API credentials

Environment Variables Required:

Variable	Description	Used By
TWITTER_API_KEY	Twitter API key	Twitter Tool
TWITTER_API_SECRET	Twitter API secret	Twitter Tool
TWITTER_ACCESS_TOKEN	Twitter access token	Twitter Tool
TWITTER_ACCESS_SECRET	Twitter access secret	Twitter Tool
OMDB_API_KEY	OMDB API Key	Movie Ratings Tool

Client Setup

The client interfaces with the Gemini model and connects to the MCP server.

cd client
npm install

Client Environment Configuration

1. Copy .env.example to .env
2. Add the GEMINI_API_KEY

Environment Variable Required:

Variable	Description
GEMINI_API_KEY	Google Gemini API integration

Running the System

Start both components in separate terminals:

Start the Server

cd server
node index.js
# or
npx nodemon index.js

The server should print a message confirming it's running.

Start the Client

cd client
node index.js

Troubleshooting

Issue	Cause	Solution
API key not found	Missing .env or wrong key	Check .env files and key values
Connection refused	Server not running	Start server before client
Tool execution failure	Incomplete API credentials	Ensure all APIs are configured
Authentication failure	Expired/invalid API tokens	Regenerate and update keys

Security Notes

• API keys are stored in .env files (excluded via .gitignore)
• Never commit your .env files to version control
• Rotate keys regularly per provider best practices
• Use firewalls or IP restrictions if deploying publicly