Warning

🚧 WIP — Active AI Pipeline Construction & Architecture Optimization in Progress.

FastAIMCP 0.1.1 [ALPHA-2026-08-26]: Model Context Protocol (MCP) Client for Java

---

⚡ Connect external Model Context Protocol (MCP) tool servers directly to Java AI agents — High-speed stdio and JSON-RPC bridge with zero framework bloat.

FastAIMCP enables FastAIAgent and FastAIRuntime to dynamically discover and invoke external tools provided by standard MCP servers (Filesystem, Git, Postgres, GitHub, Web Search, Custom CLI servers) over stdio processes with minimal IPC latency.

---

Quick Start

import fastaimcp.FastAIMCP;
import fastaimcp.McpClient;
import fastaimcp.McpTool;
import java.util.List;
import java.util.Map;

public class Demo {
    public static void main(String[] args) throws Exception {
        // 1. Launch and connect to a local MCP tool server via stdio
        McpClient client = FastAIMCP.connectStdio("npx", "-y", "@modelcontextprotocol/server-filesystem", ".");

        // 2. Discover available tools dynamically
        List<McpTool> tools = client.listTools();
        System.out.println("Discovered Tools: " + tools.size());

        // 3. Execute tool call via JSON-RPC
        String result = client.callTool("read_file", Map.of("path", "README.md"));
        System.out.println("Result: " + result);

        client.close();
    }
}

---

Table of Contents

• Why FastAIMCP?
• Quick Start
• Key Features
• Real-World Use Cases
• Architecture Overview
• API Quick Reference
• Technical Demos & Benchmarks
• Installation
• Documentation
• Platform Support
• Related Projects
• License

---

Why FastAIMCP?

Existing Model Context Protocol implementations in Java either depend on massive Spring AI stacks or lack lightweight child process lifecycle handling:

• Heavy Framework Overhead: Generic enterprise MCP wrappers drag in hundreds of megabytes of dependencies, WebClient runtimes, and complex reflection mappers.
• Fragile Stdio Piping: Standard Java Process APIs often suffer from deadlocks or unbuffered stream stalls when managing child process IPC with Node/Python MCP servers.
• Complex Agent Integration: Third-party libraries fail to provide native conversion into lightweight agent execution harnesses.

FastAIMCP solves this by providing a clean, zero-bloat stdio process bridge:

• Direct Stdio & JSON-RPC 2.0 Engine: Fast stream piping and robust process management without intermediate HTTP/SSE layers.
• FastAIRuntime Tool Bridge: Converts discovered MCP schemas directly into native FastTool instances with zero manual boilerplate.
• Zero Heavy Dependencies: Lightweight, zero-allocation JSON parsing powered by FastJSON.

Feature	Enterprise MCP Wrappers (Spring AI)	FastAIMCP
Architecture	Heavyweight dependency injection stack	Pure zero-dependency Java 17+ client (<40 KB)
Transport	Complex HTTP / SSE middleware required	Direct low-latency stdio process piping
Tool Adaptation	Framework-specific callback interfaces	1-line conversion to FastAIRuntime tools
Process Lifecycle	Manual external process orchestration	Built-in process spawn, health check & clean exit
JSON Parser	Jackson / Jackson-databind bloat	High-speed zero-allocation FastJSON

---

Key Features

• 🔌 Stdio & JSON-RPC 2.0 Engine: Low-latency, robust communication with standard MCP servers over standard input/output.
• 🛠️ FastAIRuntime Tool Bridge: Seamlessly registers remote MCP tools as native FastTool instances inside FastAIRuntime.
• 📦 Zero Heavy Dependencies: Lightweight JSON parsing powered by FastJSON.
• 🛡️ Process Lifecycle Management: Clean startup, pipe draining, health checks, and graceful shutdown of child MCP processes.
• 🔍 Schema Introspection: Automatically parses tool input schemas into strongly-typed parameter descriptions.

---

Real-World Use Cases

• 📂 External Filesystem & Git Tooling: Connect standard MCP file-system and Git servers directly into autonomous coding loops.
• 🌐 Database & API Bridges: Give AI agents instant access to Postgres, SQLite, or GitHub MCP servers without custom drivers.
• 🤖 Global Open-Source Tool Ecosystem: Leverage hundreds of community-maintained MCP servers inside FastAIAgent workflows.
• 🛠️ Developer Tool Harnesses: Orchestrate CLI and local dev-tool servers safely through unified tool permission boundaries.

---

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                         FastAIAgent                         │
│                    (Cognitive Mind Loop)                    │
└──────────────────────────────┬──────────────────────────────┘
                               │ Invokes Tool
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                        FastAIRuntime                        │
│                   (Deterministic Harness)                   │
└──────────────────────────────┬──────────────────────────────┘
                               │ Dispatches FastTool
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                          FastAIMCP                          │
│                   (Stdio / JSON-RPC Bridge)                 │
└──────────────────────────────┬──────────────────────────────┘
                               │ Stdio Pipe (Child Process)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                     External MCP Server                     │
│       (Filesystem, Git, Postgres, GitHub, Web Search)       │
└─────────────────────────────────────────────────────────────┘

---

API Quick Reference

Factory / Method	Return Type	Description	Docs
FastAIMCP.connectStdio(cmd, args...)	McpClient	Spawns and connects to an MCP process over standard I/O.	Reference
client.listTools()	List<McpTool>	Queries available tools and their JSON argument schemas.	Reference
client.callTool(name, args)	String	Invokes a specific tool and returns the JSON result payload.	Reference
client.toFastTools()	List<FastTool>	Converts all discovered MCP tools into FastAIRuntime tools.	Reference
client.close()	void	Gracefully closes streams and terminates the child process.	Reference

---

Technical Demos & Benchmarks

Case	Java Example	Launcher	Description
MCP Tool Bridge Demo	Demo.java	run-demo.bat	Discovers remote MCP tools and executes them via FastAIRuntime.
JMH Microbenchmark Suite	Benchmark.java	run-benchmark.bat	JMH throughput benchmark measuring tool adaptation and dispatch latency.

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and the dependencies to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- FastAIMCP - Model Context Protocol Bridge -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastAIMCP</artifactId>
        <version>0.1.1</version>
    </dependency>

    <!-- FastAIRuntime - Tool Execution Harness -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastAIRuntime</artifactId>
        <version>0.1.1</version>
    </dependency>

    <!-- FastJSON - Required JSON Engine -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastJSON</artifactId>
        <version>0.1.4</version>
    </dependency>

    <!-- FastCore - Required Native Loader -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>fastcore</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:FastAIMCP:0.1.1'
    implementation 'com.github.andrestubbe:FastAIRuntime:0.1.1'
    implementation 'com.github.andrestubbe:FastJSON:0.1.4'
    implementation 'com.github.andrestubbe:fastcore:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the release JARs directly from GitHub Releases:

1. 📦 FastAIMCP-0.1.1.jar (MCP Bridge Client)
2. ⚙️ FastAIRuntime-0.1.1.jar (Execution Harness)
3. 📦 FastJSON-0.1.4.jar (Fast JSON Engine)
4. ⚙️ fastcore-0.1.0.jar (Mandatory Native Loader)

---

Documentation

• REFERENCE.md: Core API reference manual and protocol contracts.
• PHILOSOPHY.md: Architectural decisions and zero-bloat design.
• COMPILE.md: Maven build guide.
• CHANGELOG.md: Project history and releases.
• ROADMAP.md: Future milestones.

---

Platform Support

Platform	Architecture	Status	Notes
Windows 10 / 11	x64	✅ Fully Supported	Stdio piping & child process lifecycle
Linux	x64 / AArch64	✅ Fully Supported	Standard POSIX stdio process execution
macOS	Apple Silicon / x64	✅ Fully Supported	Standard POSIX stdio process execution

---

Related Projects

• FastAIAgent: Autonomous ReAct Agent Loop and Cognitive Mind
• FastAIRuntime: Sandboxed Process Runner and Tool-Calling Execution Pipeline
• FastJSON: Zero-Allocation Fast JSON Engine for Java
• FastCore: Native Library Loader & JNI Utilities for Java

---

License

MIT License. See LICENSE file for details.

---

Part of the FastJava Ecosystem — Making the JVM faster. 🚀