omp-mcp
by arosyihuddin
README.md
# Toolsmith
Toolsmith is a native MCP toolchain for AI clients. It exposes workspace file operations, shell execution, filesystem search, desktop automation, host diagnostics, root-command controls, and Cloudflare Quick Tunnel management. The standalone dashboard is Toolsmith Console.
## Status
- Runtime: Bun + TypeScript.
- MCP transports: Streamable HTTP and STDIO.
- Authentication: Bearer token for internal control APIs; optional OAuth 2.0 authorization-code flow with PKCE for remote MCP clients.
- Persistence: local SQLite database with Drizzle migrations.
- Tool calls are governed by server-side exposure, permission, custom-rule, and approval policies.
- Shell execution is NOT a sandbox. Commands can access the host with the service account's permissions.
## Installation (Linux)
Toolsmith installs per user. It does not require root privileges or a system-wide `/opt` installation. The CLI stores its application, configuration, data, logs, and workspace under `~/.toolsmith/` and manages a systemd user service.
Requirements: Linux with systemd, curl, and Git. Bun is installed automatically for the current user if missing.
One-line installation:
curl -fsSL https://raw.githubusercontent.com/arosyihuddin/toolsmith-mcp/main/install.sh | bash
Or, from a clone of this repository:
bun run src/cli.ts install
The installer creates `~/.toolsmith/`, installs the production build, creates a `toolsmith` command in `~/.local/bin`, and enables/starts `toolsmith.service` through `systemctl --user`. Add `~/.local/bin` to PATH if it is not already present. The generated YAML configuration is `~/.toolsmith/config/config.yml`; persistent SQLite data is detected automatically in `~/.toolsmith/data/`.
After installation, open the printed Initial Setup URL. Create an administrator username and password; Toolsmith hashes the password and automatically generates the API token and sudo encryption key. Initial Setup requires a one-time token printed by the installer. If you need to generate or rotate it later, run `toolsmith setup-token` on the server. The setup page can be opened through localhost, a LAN address, or a public HTTPS domain/reverse proxy; localhost is not required. For direct LAN access, configure `server.host: 0.0.0.0` and restrict the port with your firewall. Keep the setup token private and use HTTPS when setting up through an untrusted network. The optional public HTTPS origin enables OAuth discovery for remote MCP clients. After setup, sign in to manage and view or regenerate the API token.
After installation, manage Toolsmith with:
toolsmith status
toolsmith logs
toolsmith restart
toolsmith update
toolsmith update --nightly
toolsmith version
toolsmith uninstall
`toolsmith update` installs the latest official, non-prerelease GitHub Release (stable channel). `toolsmith update --nightly` installs the latest commit from the `main` branch and may include unfinished changes. `toolsmith version` and `toolsmith status` show the installed version, channel, and source commit. A normal installation starts on the stable channel; installing from a local source directory is marked as `local`.
Uninstall preserves configuration and user data. Use `toolsmith uninstall --purge` only when you also want to delete all of `~/.toolsmith/`. The service runs as a systemd user service; enable lingering separately if it must stay active after logout.
## Development
Requirements: Bun 1.4+ and Linux for the recommended deployment and desktop integrations.
bun install
bun run dev
Validate changes locally:
bun run typecheck
bun test
bun run build
HTTP integration tests use an isolated test environment and dedicated loopback ports. Never point tests at a production port, database, or credentials.
## MCP connection
Default Streamable HTTP endpoint: http://127.0.0.1:48765/mcp
Choose transport with MCP_TRANSPORT=http|stdio|both. Configure the listener using MCP_HTTP_HOST, MCP_HTTP_PORT, and MCP_HTTP_PATH.
## Configuration
Development runs read `config.yml` from the repository root. Installed production deployments use `~/.toolsmith/config/config.yml`. Set `TOOLSMITH_CONFIG` to override either path. Environment variables override YAML values. Keep local `config.yml` credentials private; the file is excluded from Git.
| Variable | Purpose |
| --- | --- |
| TOOLSMITH_API_TOKEN | Internal HTTP/control API Bearer token. |
| TOOLSMITH_DEFAULT_CWD | Default workspace. |
| TOOLSMITH_DATA_DIR | Control-plane database directory. |
| TOOLSMITH_SUDO_ENCRYPTION_KEY | Stable secret of at least 32 characters. Keep this key unchanged while encrypted root-command credentials exist. |
| Admin account | Created through the built-in Toolsmith Initial Setup UI; password is stored as a scrypt hash. |
| TOOLSMITH_TERMINAL_ROOT | Root for relative terminal paths. |
| MCP_PUBLIC_URL | Public HTTPS origin for OAuth discovery and callbacks; configured during Initial Setup or in config.yml. Unset disables remote OAuth. |
| LOG_LEVEL | Log level; defaults to info. |
Example user configuration (config.example.yml):
server:
transport: http
host: 127.0.0.1
port: 48766
path: /mcp
security:
api_token: replace-with-a-random-secret
sudo_encryption_key: replace-with-a-stable-secret
logging:
level: info
# directory: ~/.toolsmith/logs
Do not commit tokens, OAuth credentials, sudo passwords, or encryption keys. Changing the sudo encryption key makes previously encrypted passwords unreadable.
## Tool catalog and policy
### Reset administrator password
If the Toolsmith OAuth administrator password is lost, run this command on the
same Linux account that owns the Toolsmith installation:
toolsmith reset-password
The command prompts for the new password without echoing it, requires at least
8 characters, updates the local administrator credential hash, and revokes
all existing administrator browser sessions. It does not change the API token
or existing OAuth access/refresh tokens. No service restart or sudo access is
required.
GET /api/tools is the source of truth consumed by Toolsmith Console. The catalog includes filesystem/workspace tools, desktop automation, system diagnostics, root-command execution, and tunnel management. Exposure, permissions, custom rules, and approval decisions are enforced by the backend, not by the UI. Root-command allow rules match exact commands and arguments; seeded shutdown/reboot examples remain disabled by default.
A configured working directory is a default cwd, not a filesystem or process sandbox. Treat tool arguments, paths, URLs, browser state, and client metadata as untrusted.
## Toolsmith Console
The dashboard frontend lives in the separate toolsmith-console project and consumes authenticated /api/* endpoints. Update and test both repositories when API contracts change.
## Deployment
Install and manage Toolsmith with the per-user CLI workflow. It stores the application, configuration, database, workspace, and logs under `~/.toolsmith` and manages `toolsmith.service` through the systemd user manager.
## Engineering rules
See ARCHITECTURE.md for runtime boundaries, lifecycle requirements, security constraints, and testing standards. Keep changes local until typecheck, tests, build, and diff review pass. Deployment is a separate explicit step.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessOutdated data