Machai is a multi-module Java toolkit for GenAI-enabled developer automation. It provides provider-neutral generative-AI access, embedding support, Bindex library discovery, Model Context Protocol (MCP) servers, Maven integrations, and Ghostwriter workflows for repeatable, maintainable AI-assisted development.
Automate application assembly using semantic search for smart library selection on the Machanism platform.
Estrellas
4
Herramientas
—
Disponibilidad
—
Cloning and Getting Started
To clone and set up this project locally, follow these steps:
Clone the repository:
git clone https://github.com/machanism-org/machai.git
cd machai
git submodule update --init --recursive
Utility library for describing, detecting, and resolving conventional project directories. It gives build tools, scanners, generators, and plugins a consistent model for source, test, resource, and documentation locations across Maven, Gradle, JavaScript, Python, and fallback layouts.
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, prompts, and resources.
Java 17 Model Context Protocol server runtime that exposes functional tools and prompts through STDIO or HTTP, including stateless and streamable HTTP modes; domain-specific tools remain in separate runtime libraries.
Maven plugin that starts the Machai MCP Server for a Maven project over HTTP. Its aggregator goals provide stateless or streamable transport and supply project metadata, parameters, tools, and project-directory context.
AI-powered project-wide processing engine and command-line tool for source code, tests, documentation, site content, configuration, diagrams, and other project files. It uses embedded guidance and reusable Acts for repeatable AI-assisted automation.
Python 3.9-or-newer API and command-line wrapper around Ghostwriter. It bundles the Java runtime with mgw, validates JAVA_HOME, and starts JPype lazily. Its gw, gdp, and adw functions support CLI invocation, guidance processing, and Act execution; direct processor calls can resolve local JARs or Maven coordinates through jgo and return ordinary Python results.
Primary Maven adapter for Ghostwriter. It runs guidance-driven processing or named and prompt-based Acts over selected project files, with project-wide and per-module goals, Maven settings integration, and Java class-introspection tools.
Runnable Java 17 MCP server that packages Ghostwriter workflows, Bindex metadata services, and the Machai MCP runtime. It exposes project-assistance, metadata retrieval, registration, and library-recommendation capabilities through STDIO or HTTP.
Maven plugin that generates and registers Bindex metadata for Maven projects and reactor builds. It provides reactor-wide and per-module goals that delegate generation and registration to Ghostwriter and Bindex Core workflows.
Standalone Java 17 distribution packaging Bindex Core with the Machai MCP runtime. It exposes complete or GraphQL-filtered metadata retrieval, validation and registration from JSON, files, or URLs, schema access, and natural-language library recommendations through STDIO or HTTP. Recommendations use classification, embeddings, and MongoDB-backed search with language, layer, score, and version filters.
Project Structure
Machai is a Maven parent project that coordinates eleven cooperating modules: foundation libraries, core AI services, language integration, Maven build integrations, and ready-to-run MCP server distributions. Project Layout supplies shared directory resolution, and GenAI Client supplies provider, embedding, and tool abstractions. The Machai MCP Server provides the reusable MCP runtime; Bindex Core and Ghostwriter build on the foundation libraries; Ghostwriter-Py embeds the Ghostwriter processor for Python callers; Maven plugins invoke their corresponding runtime services; and the server distributions publish Bindex and Ghostwriter capabilities to MCP clients. External AI providers serve the GenAI client, while Maven builds invoke the plugins. Each module is a Git submodule, and each link targets its corresponding remote GitHub repository at the recorded submodule commit rather than a relative path in the parent repository.
The architecture groups the modules into foundation libraries, core services, language integration, Maven build integration, and ready-to-run MCP server distributions. External AI providers supply the GenAI client, Maven invokes the build plugins, and MCP clients consume the packaged server capabilities. Bindex Maven Plugin uses GW Maven Plugin and Bindex Core, while the Ghostwriter packaging profile includes Bindex tools, also available transitively to the Python integration. No rendered project-structure image is available in the configured site resources, so the overview remains textual.
Introduction
Applications can use the GenAI client directly, expose tools through MCP, discover reusable libraries through Bindex, or automate repository-wide updates to source code, tests, documentation, configuration, diagrams, and other project files with the Ghostwriter command line and Maven plugin. The modules are designed to work independently where appropriate and together for end-to-end AI-assisted development workflows.
Requirements and Build
JDK 17 or newer is required to build the complete reactor. Several libraries target Java 8 bytecode, while the MCP server components and Bindex Core require Java 17.
Apache Maven 3.8.1 or newer.
Git and network access to download dependencies.
Provider credentials and service configuration when running GenAI, Bindex, or custom functional-tool workflows.
Run the full verification suite with:
mvn clean verify
To build and stage the project site, first set MACHAI_SITE to a writable staging directory used by the site's post-processing configuration:
mvn clean install site site:stage
Set MACHANISM_PACK_DIR before running mvn -Ppack install when a packaging profile needs to create a CLI or server distribution. Reactor-wide packaging also builds the Python wrapper and requires Python 3.9 or newer with the build package installed (python -m pip install build). Set JAVA_HOME before using the Python wrapper.
Usage
Add a library dependency
Add a published module to your Maven project, selecting the version you require:
These commands require the assembled JAR containing runtime dependencies; substitute its actual output path and your tool library paths. On Windows, quote the classpath and separate entries with ; instead of :, for example java -cp "path/to/machai-mcp-server.jar;path/to/functional-tools.jar" org.machanism.machai.mcp.server.McpServer --port 45000. Connect an HTTP MCP client to http://localhost:45000/mcp; add --session for streamable HTTP sessions.
Run Ghostwriter from Maven
Process guidance-tagged files:
mvn org.machanism.machai:gw-maven-plugin:gw
Run an Act or direct prompt for 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.
Use the CLI, Python wrapper, and metadata tools
From an unpacked Ghostwriter delivery pack, inspect the CLI options or process a selected path:
With Python 3.9 or newer and JAVA_HOME configured, install the wrapper and inspect its CLI:
python -m pip install mgw
python -m mgw --help
The wrapper exposes gw, gdp, and adw for Python applications. Use Bindex Maven Plugin's bindex and register goals to generate and publish metadata, or their -per-module variants for reactor module processing. MCP Server Maven Plugin's stateless and streamable goals launch an HTTP endpoint from Maven with -Dmcp.port=45000 -Dmcp.config=gw.properties. The Ghostwriter and Bindex MCP distributions package their respective tools for MCP clients; consult the linked module documentation for service configuration and packaging details.
Troubleshooting and Debugging
Modules that include the SLF4J SimpleLogger binding can be configured with simplelogger.properties on the runtime classpath, commonly in src/main/resources. This example enables a global level and package-specific levels, writes to standard output, and configures the log layout:
Set org.slf4j.simpleLogger.logFile=System.err for standard error, or set it to a writable file path such as logs/machai.log; its parent directory must exist. Package-specific settings override the default level. Valid levels are trace, debug, info, warn, error, and off.
Override the same properties at launch without changing classpath resources:
Place JVM properties before -jar. If a change does not take effect, confirm that slf4j-simple is present at runtime, simplelogger.properties is on the effective classpath, and another SLF4J provider has not been selected.
Contributing
Open an issue for a bug, documentation gap, feature proposal, or design question.
Create a focused branch from main and keep changes limited to the stated problem.
Follow the existing Java and Markdown style, preserve guidance comments, and update relevant documentation when behavior changes.
Add or update tests, run mvn clean verify, and submit a pull request with a clear summary, testing details, and configuration or compatibility impact.
Address review feedback and keep the branch synchronized with the target branch.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Machai?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Machai necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Machai?
Machai se ejecuta localmente por stdio.
¿Cuándo se comprobó Machai por última vez?
Última comprobación: 2026-11-16. Automate application assembly using semantic search for smart library selection on the Machanism platform.