Harnios MCP

Harnios gives AI assistants and the owner-facing web app one shared Company OS workspace. Files, operating instructions, scheduled tasks, and app state live in a configured S3-compatible bucket. The same Next.js application serves the web interface and the authenticated MCP endpoint at /mcp.

The app lives in frontend/. This repository does not include a local MinIO service or a ready-made MCP client configuration; bring an existing S3-compatible bucket and your own credentials. A separately hosted MinIO service remains compatible.

What you can do

• Browse, upload, create, edit, delete, and download files at /files. Markdown, CSV, HTML, Python, and other text files have editor or preview modes; binary files can be opened or downloaded where supported. Moving or renaming a file is available through the move MCP tool.

• Open .bpmn files as diagrams, inspect or edit their XML, and make visual changes in a Modeler modal. Apply updates the unsaved editor state; Save persists it. New BPMN diagram is offered only in direct process folders at /processes/<process> and creates a valid starter file without replacing an existing one. BPMN specification

• Create expiring, read-only file links with optional password protection. View supported formats in the browser, use native sharing where available, and revoke links at /shares. Shares last at most 30 days. Sharing specification

• Use the floating chat on authenticated pages. Harnios mode can use enabled MCP tools; General mode has no MCP tools. Tool activity, Stop, and Reset controls are visible. The conversation survives client-side navigation but not a full reload. Chat specification

• Manage native and connected tools at /tools, connect external MCP servers at /tools/connections, and create or run Scheduled Tasks at /schedules. In-app help is at /docs; the same topics are available to assistants through get_docs.

Related MCP server: BaseMouse

Get started

1. Prepare an existing S3-compatible bucket and credentials that can read and write it. Harnios does not create the bucket.

2. From the repository root, copy the application environment template and fill in its required values:

   cp frontend/.env.example frontend/.env.local

   Set S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, OAUTH_OWNER_USERNAME, and OAUTH_OWNER_PASSWORD. Set S3_FORCE_PATH_STYLE for your provider (false for providers requiring virtual-hosted-style bucket addresses). Keep frontend/.env.local private.

3. Install and start the application:

   cd frontend
   npm ci
   npm run dev

4. Open http://localhost:3000/init. If storage is unavailable, this page explains what configuration is missing; enter the values locally or in your hosting platform and restart. After connecting storage and signing in, use /init to bootstrap an empty Company OS, then open /files or connect an assistant to http://localhost:3000/mcp.

The bucket holds workspace files and application state; no separate application database is required. The old bundled MinIO setup has been removed. If you previously used it, ignored data under data/minio is not deleted or migrated: copy anything you still need into your chosen bucket with an appropriate storage client. Older SpecKit quickstarts may still describe that historical setup; use the steps above for current installations.

Configuration by capability

See frontend/.env.example for the complete variable list and comments. Secrets belong in private environment settings, never in the README or a committed client configuration.

MCP access and tools

/mcp is a Streamable HTTP endpoint. Clients authenticate with OAuth 2.0 or an owner-created personal access token; the owner manages connections and tokens under /settings. For each task, the first storage call must read AGENTS.md via read_file. The server rejects other tool calls until that bootstrap succeeds; if AGENTS.md is missing, it directs the client to the OS repair flow. Bootstrap specification

The application registers 22 native tools. The table reflects the registration code, not merely the /tools display catalog. An owner may disable tools; a disabled tool is absent from the live MCP list. Externally connected servers may add more tools, so the live set depends on configuration and connection state.

run_python accepts inline code or a stored .py file, not both, and has a maximum 20-second timeout. run_job returns a summary and output metadata rather than file contents. External MCP tools are exposed through the same endpoint when their connection is enabled, their names do not collide with native tools, and they have not been disabled. The internal scheduler uses the native tool set, not external proxy tools. External connections · Scheduled Tasks

Note: get_change_process is registered but is currently missing from the owner-facing /tools catalog. It is still subject to the server's tool gate; its status just cannot be changed from that page until the catalog is corrected.

Web interface

The /files area and management pages require an owner session. Temporary visitor links are limited to the shared file; they do not grant access to the workspace or its edit controls. The previous /editor path redirects to /files.

Deploy

For Vercel, import this repository with Root Directory set to frontend/ and configure the same environment variables in the project settings. Set PUBLIC_APP_URL to the deployed public origin for visitor-facing links. The app is stateless apart from its external bucket, but the in-process scheduler does not run on Vercel; use a persistent single-instance deployment when Scheduled Tasks must run automatically.

GitHub Actions builds and publishes ghcr.io/harnios/harnios-mcp after successful pushes to main. Coolify can run that image with its own runtime environment settings. For a local application image build, use docker build -t harnios-mcp:local frontend/. The image does not contain an object-storage server. No commit or deployment occurs merely by changing this README.

License

Licensed under the PolyForm Internal Use License 1.0.0: internal use is permitted; distribution or offering a product or service based on it requires a separate agreement with the copyright holder.