Skip to main content
Glama
README.md
# ICHIGO MCP

A local-first, developer-focused MCP server for Windows.

## Current scope (v0.1)

- Local MCP over stdio (no public network listener).
- Read-only project discovery and file inspection.
- Workspace-scoped file creation and edits.
- Developer command runner with executable allowlist and timeout.
- Explicit confirmation for overwrites, deletions, and command execution.
- Manual start only.

## Requirements

- Windows 10/11
- Python 3.11+
- Internet connection for the first dependency install

## Quick start

1. Open PowerShell in this folder.
2. Install the environment once:

   `powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1`

3. Configure an MCP-compatible host using the stdio example below.
4. To launch the server manually for a host/test harness, run:

   `powershell -ExecutionPolicy Bypass -File .\scripts\start.ps1`

The stdio server is intended to be launched by an MCP-compatible host. Do not run it as a public web service.

## Workspace security

By default, ICHIGO MCP can access only the `workspace` folder inside this project. Put a project there, or add another explicitly trusted absolute path to `config.json` under `allowed_roots`.

All file paths are resolved and checked against these roots. Directory traversal and symlink escapes are rejected.

## Hybrid permission model

- Reads and directory listings: allowed automatically inside configured roots.
- Create new files: allowed inside configured roots.
- Overwriting existing files, deleting files, and command execution: require `confirm=true`.
- Commands are launched without a shell and must use an allowlisted executable.
- Timeouts and output limits are enforced.

A host may additionally display its own per-tool approval UI. Tool-level confirmation remains enforced by the server.

## MCP client configuration

Example for an MCP host that supports stdio. Replace the paths with the actual repository location on your machine.

```json
{
  "mcpServers": {
    "ichigo-mcp": {
      "command": "C:\\path\\to\\desk-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "ichigo_mcp.server"],
      "cwd": "C:\\path\\to\\desk-mcp",
      "env": {
        "ICHIGO_CONFIG": "C:\\path\\to\\desk-mcp\\config.json"
      }
    }
  }
}
```

## Current limitations

This milestone does not yet provide remote access, screenshots, mouse/keyboard control, background startup, or a hosted gateway. Those should be added only after local tools and permission boundaries are tested. Direct ChatGPT connectivity depends on the ChatGPT plan and supported custom MCP connection options.

## Development

```powershell
.\.venv\Scripts\Activate.ps1
python -m pytest
python .\scripts\smoke_test.py
```