Fork me on GitHub

Machai Project

Machai is a multi-module Java toolkit for GenAI-enabled developer automation. It provides provider-neutral GenAI access, embedding support, Bindex library discovery, an MCP server, Maven integrations, and Ghostwriter workflows that can process source code, tests, documentation, site content, configuration, diagrams, and other project files.

The project is designed to make AI-assisted development repeatable and maintainable. Applications can use the GenAI client directly, expose tools through MCP, discover reusable libraries through Bindex, or automate repository-wide updates through the Ghostwriter command line and Maven plugin.

Modules

Name Description
Project Layout A utility library for describing and resolving conventional project directories such as production sources, test sources, resources, and documentation. It gives build tools and plugins a consistent project-structure model across Maven, Gradle, JavaScript, Python, and fallback layouts.
GenAI Client A provider-neutral Java library for generative AI integrations. It supports prompt execution, embeddings, provider resolution, usage tracking, web search, MCP servers, and registration of Java methods as AI-callable tools and prompts.
Machai MCP Server A Java 17 Model Context Protocol server that exposes Machai functional tools and prompts through STDIO or HTTP transport. It supports stateless and streamable HTTP modes while keeping domain-specific tools in separate runtime libraries.
MCP Server Maven Plugin A Maven plugin that launches the Machai MCP Server for a Maven project over HTTP. Its stateless and streamable goals supply project metadata, parameters, tools, and the project directory to the server.
Bindex Core Core services for Bindex metadata retrieval, registration, semantic library recommendation, classification, embeddings, and MongoDB-backed persistence. It supports Ghostwriter, Maven plugins, MCP workflows, and AI-assisted project assembly.
Ghostwriter An advanced documentation engine and command-line processor that scans, analyzes, and assembles project documentation using embedded guidance tags and AI-powered synthesis. Its pack profile also supplies Bindex integration for repository-wide documentation and library-indexing workflows.
GW Maven Plugin A Maven plugin for Ghostwriter documentation automation. It scans and updates project documentation using guidance tags and AI-powered synthesis, with goals and configuration intended to keep documentation consistent and current across Maven modules.

Project Structure

The project is organized as a Maven parent and seven cooperating modules. The parent coordinates the build and module lifecycle. Project Layout supplies shared directory resolution; GenAI Client supplies provider and tool abstractions; and the MCP server builds on that client to publish runtime capabilities. The MCP Maven plugin launches the server from Maven. Bindex Core adds metadata, embeddings, persistence, and semantic library discovery. Ghostwriter combines project layout and GenAI processing for guided repository automation, while the GW Maven Plugin adapts that automation to Maven projects. The dependency flow is from the parent to each module, with the MCP server using GenAI Client, Bindex Core using GenAI Client, Ghostwriter using Project Layout and GenAI Client, and the Maven plugins using their corresponding server or Ghostwriter runtime.

Machai project structure

Installation

Prerequisites

  • A JDK 17 or newer to build the complete reactor. The MCP server, MCP server Maven plugin, and Bindex Core require Java 17; Project Layout, GenAI Client, Ghostwriter, and GW Maven Plugin target Java 8 bytecode.
  • Apache Maven 3.8.1 or newer.
  • Git and network access to clone the repository and download dependencies.
  • Provider credentials and service configuration when using GenAI, Bindex, or custom functional tools.

Build from source

Clone the repository and build all modules:

git clone https://github.com/machanism-org/machai.git
cd machai
mvn clean verify

To build the site and stage its generated pages, use:

mvn clean install site site:stage

Some packaging profiles use MACHANISM_PACK_DIR for delivery artifacts. Set that environment variable before running mvn -Ppack install when a packaged CLI or server distribution is required.

Usage

Use a library

Add a published module as a Maven dependency. For example:

<dependency>
  <groupId>org.machanism.machai</groupId>
  <artifactId>genai-client</artifactId>
  <version>RELEASE</version>
</dependency>

Use the module pages for provider configuration, API details, and workflow-specific examples.

Run the MCP server

Build the server with its packaging profile, add functional tool libraries to the runtime classpath, and start STDIO mode:

mvn -pl machai-mcp-server -Ppack install
java -cp path/to/machai-mcp-server.jar:path/to/functional-tools.jar org.machanism.machai.mcp.server.McpServer

Start HTTP mode on port 45000:

java -cp path/to/machai-mcp-server.jar:path/to/functional-tools.jar org.machanism.machai.mcp.server.McpServer --port 45000

Run Ghostwriter through Maven

Process files containing guidance tags:

mvn org.machanism.machai:gw-maven-plugin:gw

Run an Act or direct prompt against a selected path:

mvn org.machanism.machai:gw-maven-plugin:act -Dgw.act="review Focus on public APIs" -Dgw.path=src/main/java

Configure the required AI provider, model, credentials, Bindex repository, and tool-specific settings before running AI-backed workflows.

Troubleshooting and Debugging

Machai uses SLF4J SimpleLogger in modules that provide a SimpleLogger binding. Configure it with a simplelogger.properties file on the runtime classpath, normally under src/main/resources or beside the application resources. The following example enables debug logging globally, enables trace logging for Machai packages, writes logs to standard output, and uses a readable timestamped layout:

org.slf4j.simpleLogger.defaultLogLevel=info
org.slf4j.simpleLogger.log.org.machanism=debug
org.slf4j.simpleLogger.log.org.machanism.machai=trace
org.slf4j.simpleLogger.logFile=System.out
org.slf4j.simpleLogger.showThreadName=true
org.slf4j.simpleLogger.showLogName=true
org.slf4j.simpleLogger.showShortLogName=true
org.slf4j.simpleLogger.levelInBrackets=true
org.slf4j.simpleLogger.showDateTime=true
org.slf4j.simpleLogger.dateTimeFormat=yyyy-MM-dd HH:mm:ss.SSS

Set org.slf4j.simpleLogger.logFile=System.err to send output to standard error, or set it to a writable path such as logs/machai.log to use a dedicated log file. The parent directories must already exist and the process must have permission to write there. Package-specific settings override the default level; valid levels include trace, debug, info, warn, error, and off. Remove a package-specific property when the global level should control that package.

The same settings can be supplied as JVM system properties and are useful when launching a packaged jar without changing its resources:

java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug \
     -Dorg.slf4j.simpleLogger.log.org.machanism.machai=trace \
     -Dorg.slf4j.simpleLogger.logFile=System.err \
     -Dorg.slf4j.simpleLogger.showDateTime=true \
     -jar machai-mcp-server.jar

On Windows, use the equivalent single-line command, for example java -Dorg.slf4j.simpleLogger.defaultLogLevel=debug -Dorg.slf4j.simpleLogger.logFile=System.out -jar machai-mcp-server.jar. JVM properties must be placed before -jar. If logging changes do not take effect, check that slf4j-simple is present at runtime, that simplelogger.properties is on the effective classpath, and that no other SLF4J provider is selected.

Contributing

  1. Open an issue to describe a bug, documentation gap, proposed feature, or design question.
  2. Create a focused branch from the main branch and keep changes limited to the stated problem.
  3. Follow the existing Java and Markdown style, preserve guidance comments, and update relevant module documentation when behavior changes.
  4. Add or update tests for code changes and run mvn clean verify before submitting.
  5. Submit a pull request with a clear summary, testing details, and any configuration or compatibility impact.
  6. Respond to review feedback and keep the branch synchronized with the target branch.

License

Machai is distributed under the Apache License, Version 2.0. The project POM declares this license for all modules.

Contact and Support