tersePrompts/fastMCP4J

**Annotate a Java class. Ship an MCP server.**
Tools, resources, prompts, memory — and a sandboxed bash terminal that can't
touch your machine. No boilerplate, no containers, no 50-jar framework.
**AI Agents →** Share this skill with Claude for code generation
FastMCP4J is an annotation-driven SDK for the
Model Context Protocol (spec 2.0.1) on
Java 17+. One annotation turns a class into an MCP server; one more gives your
AI agent a real terminal — **a bash sandbox where the host is unreachable by
construction**. Cold start in under 500 ms, twelve dependencies, everything
testable in-process.
> **Status**: beta (v0.5.0-beta) — API stable, 235 tests passing, published to
> Maven Central.
---
Quick start (2 minutes)
**Maven**
**Gradle**
That's the whole install story: **Java 17+**, one artifact on Maven Central,
MCP Java SDK 2.0.1 underneath. No annotation processor, no codegen step, no
container runtime.
Create your server
**That's it. Your MCP server is running.**
**Working example**: EchoServer.java
---
Why this exists
Every Java team wiring AI agents to tools faces the same choice, and every
option hurts:
| | Raw MCP SDK | Spring AI / LangChain4j | **FastMCP4J** |
|---|---|---|---|
| Lines per tool | 35+ | varies, plus framework glue | **~8** |
| Dependencies | 1 + your patience | 30–50+ jars | **12 jars** |
| Startup | fast | framework-sized | ** **Before:** a day of JSON-schema plumbing per tool, and shell access means a
> rogue prompt is a node down.
> **After:** annotations on Tuesday, agents in production Wednesday — and the
> terminal they use can't touch your disk.
---
The API tour
1 · Make a tool — sync or async
2 · Built-in brains — one annotation each
| Annotation | Tools you get |
|------------|---------------|
| @McpMemory | list, read, create, replace, insert, delete, rename |
| @McpTodo | add, list, updateStatus, updateTask, delete, clearCompleted |
| @McpPlanner | createPlan, listPlans, getPlan, addTask, addSubtask |
| @McpFileRead | readLines, readFile, grep, getStats |
| @McpFileWrite | writeFile, appendFile, writeLines, deleteFile, createDirectory |
3 · Sandboxed bash — give the agent a terminal, not your machine
Scripts run in a bashkit4j
in-memory sandbox: POSIX-style bash with 160+ commands re-implemented
natively, a virtual filesystem, network denied by default. **No real bash is
ever spawned.** Then the agent calls the bash tool:
| | Host shell (ProcessBuilder, Docker) | **Sandbox mode** |
|---|---|---|
| Real bash on the host | ✅ runs — full attack surface | **❌ never — bash re-implemented natively** |
| Host filesystem visible | ✅ all of it | **❌ invisible until you mount, read-only by default** |
| OS processes per command | ✅ one per call | **❌ zero — in-process** |
| Network access | ✅ open | **❌ denied by default** |
| One rogue script | node down | **sandbox reset** |
State persists across calls (cwd, env, files) — multi-step agent workflows
work. Mounts are enforced inside the native library: canonicalized,
symlink-safe, and impossible without allowMountsUnder. Need the real shell
for trusted automation? mode = BashMode.HOST keeps the legacy tool with its
path guardrails.
> Sandbox mode requires the optional
> io.github.terseprompts:bashkit4j:0.2.0 dependency — native libs for
> Windows/Linux/macOS (x86-64 + ARM64) are bundled and auto-detected.
> **🔭 Future scope — a third mode, BashMode.DOCKER.** The isolation ladder
> gets one more rung: HOST = the full computer (trusted use) → SANDBOX =