Content
# allcanuse-mcp
An MCP Server for Windows / Linux experimental environments, used to expose common local operation capabilities to local Agent / MCP Client.
License: `MIT`
The goal of `allcanuse-mcp` is not just to provide a few scattered small tools to the model, but to systematically expose the capabilities of the experimental machine to the model.
After connecting, the model can not only read files and run commands, but also use the local machine as an operable workstation.
Currently, it provides `90+` tools, and the core capabilities include:
- System and environment detection: read system architecture, time, disk space, environment variables, network configuration, network adapter, current IP and basic running environment information
- Command execution and automation: execute cross-platform shell, Windows `cmd`, PowerShell, support for continuing to use command output for subsequent decisions
- Process and port management: start process, end process, list process, view process tree, locate port corresponding process, enumerate listening ports and established connections; also supports registration and protection of long-running experiments/training/inference processes to prevent model mis-killing
- File and code editing: directory tree traversal, search by file name, search by text, read long files in segments, precise line replacement, fixed text replacement, text file writing, JSON reading and writing, binary reading and writing, hash, recent files, desktop file viewing
- Development assistance and engineering operations: compression and packaging, decompression and archiving, configuration modification, source code positioning, local patching, running verification commands, suitable for letting the model directly do bug fixing, configuration modification, script writing, and project organization
- Webpage and HTTP operations: HTTP requests, HEAD detection, response header acquisition, webpage content extraction, webpage conversion to Markdown, link extraction, table extraction, specified HTML element extraction, webpage form submission, file upload, file download, and jump chain tracking
- Network diagnosis and protocol debugging: DNS resolution, reverse resolution, TLS certificate reading, ping, route tracking, TCP connectivity testing, raw TCP transmission and reception, UDP transmission and reception, WebSocket debugging, and small-range port scanning
- Desktop and window observation: enumerate windows, get foreground window, summarize desktop context, capture desktop screenshots, suitable for combining with vision-enabled models to work together
- Visual and audio collection: enumerate local cameras and take photos, also call the local binary tools built into the repository to record microphone audio, suitable for experimental scenarios that require multimodal input
- Duty and long task hosting: wait for time, wait for file/process/port/HTTP/window/desktop changes, background duty tasks, task scheduling, task events, task product recording, and disconnection summary
- Native tools and multi-language extensions: in addition to Python tools, you can also write C language and other technical stacks into the repository's built-in local executable tools and let the model directly call them, covering more underlying, higher-performance, or more system-interface-close capabilities
- Model self-inspection and self-discovery: can directly list all tools and complete descriptions, making it convenient for the model to decide what to call next in unfamiliar tasks
## What can the model do after connecting
After connecting to this MCP, the model can do more than just "answer questions", but actively promote tasks on the local machine, such as:
- Help you troubleshoot "why a service can't be started": first look at the port, then look at the process, then look at the log, then send an HTTP request, and finally give a positioning result
- Help you modify code and repair configuration: first search for target files and functions, then read large files in segments, precisely modify a few lines of code, and then automatically run verification commands
- Help you read webpages and organize materials: not only grab the current page content, but also continue to extract links within the site, chapter pages, detail pages, tables, structured metadata, and attachments, and progressively collect content related to the task from the entire website
- Help you do more like "research assistant"-style webpage exploration: the model will first judge whether the current page is a content page, directory page, index page, or document homepage, and then decide to continue grabbing content, extracting links, reading metadata, or crawling multiple sub-pages in batches, rather than mechanically running through a set of fixed URLs
- Help you dynamically expand website content according to task goals: for example, first read the document homepage, and then continue to the installation page, API page, FAQ page, and download page; or first read the article page, and then continue to the related detail page and attachment link to supplement the context
- Help you judge while crawling: the model can determine which page to continue reading, which page to skip, which attachment to download, and which table or element to extract based on the title, content, canonical, Open Graph, JSON-LD, link text, and page structure it has crawled
- Help you connect webpage crawling and local workflow: after crawling content, not only return raw text, but also continue to download files, save results, organize into Markdown, extract tables, and then combine with local code, logs, and network status for analysis
- Help you check local network issues: look at DNS, ping, port, TLS, routing, and connection status to determine if it's a resolution issue, host unreachable, port blocked, or application-layer anomaly
- Help you automatically observe desktop changes: monitor the installer, monitor window pop-up, monitor foreground switching, and automatically capture screenshots, suitable for GUI tasks in experimental environments
- Help you collect experimental input materials: the model can not only capture screenshots and take photos, but also call local native audio recording capabilities to collect microphone input when needed, making it convenient for experimental processes such as voice, meetings, interviews, and environmental sound
- Help you upload and download local files: upload logs, compressed packages, and build products to the interface, and also pull network files to the local machine like a lightweight version of `wget`
- Help you do long-term duty: after the user temporarily leaves, continue to wait for file generation, service recovery, window appearance, and then quickly take over through handover summary when returning
- Help you automate experiments in virtual machines: hand over the entire process of "observation -> judgment -> execution -> verification" to the model, rather than just letting the model stay at the level of verbal suggestions
- Help you host ultra-long experiment processes: for training, inference, services, or batch processing tasks that take hours to days to run, the model can register them as protected long-term processes, and stdout/stderr will be written to persistent logs; even if the AI session or client connection is interrupted, the local process can still continue to run, and the status and log tail can be read and continued after the next connection
- Help you use native programs built into the repository to do more underlying work: when certain tasks are more suitable for processing with C or local executable programs, the model can directly call these built-in tools, rather than limiting all capabilities to the Python layer
If you want the model to be a truly hands-on local assistant, rather than just talking without doing, `allcanuse-mcp` is positioned to hand over these capabilities to the model.
## Quick Start
Currently, mainstream AI clients usually only need to:
1. Install dependencies
2. Configure MCP in the client
3. Restart the client
No need to manually start the server process, the client will automatically start it according to the configuration.
### 1. Install dependencies
First, install the basic runtime dependencies of the current project:
```powershell
pip install -r requirements.txt
```
If you are a developer, or want a shorter local command, you can also:
```powershell
pip install -e .
```
### 2. Configure MCP in the client
#### ChatGPT Codex / Codex CLI
The configuration file is usually:
```text
~/.codex/config.toml
```
Example:
```toml
[mcp_servers.allcanuse]
type = "stdio"
command = "python"
args = ["run_server.py", "--transport", "stdio", "--profile", "codex"]
cwd = "D:/path/to/allcanuse"
enabled = true
startup_timeout_ms = 30000
tool_timeout_sec = 180
```
If using Codex on macOS and wanting to explicitly use the built-in `stdio` compatibility layer, you can write it in a more complete form:
```toml
[mcp_servers.allcanuse]
type = "stdio"
command = "/opt/homebrew/bin/python3"
args = ["run_server.py", "--transport", "stdio", "--profile", "codex"]
cwd = "/Users/you/path/to/allcanuse-mcp"
enabled = true
startup_timeout_ms = 30000
tool_timeout_sec = 240
```
Codex recommends explicitly adding `--profile codex`. This profile will prioritize retaining desktop observation, screenshot, camera, duty/background tasks, long-term process registration, and Microsoft document inspection capabilities not native to Codex, and hide `run_shell`, `read_file`, `patch_lines`, and `fetch_webpage_text` capabilities already provided natively by Codex to reduce initialization context and tool selection overhead.
No need to configure additional compatibility switches here, just keep `--transport stdio`. The current `stdio` startup entry will automatically be compatible with `Content-Length` framing that Codex may use, as well as other common line-by-line JSON input and output for clients. If Codex appears to have empty tool call results, initialization timeouts, or see `Content-Length: ...` being parsed as JSON in stderr, first confirm that the local code has been updated to include `src/allcanuse_mcp/stdio_compat.py`, and then completely restart Codex to let it restart the MCP server.
Note: under `--profile codex`, `list_all_tools()` will only list the streamlined toolset currently exposed to Codex. When you need more than 100 tools, change the parameter to `--profile full`, or set the environment variable `ALLCANUSE_MCP_PROFILE=full` and restart the client.
Usually, there is no need to change `args` to `["stdio_compat.py", "--transport", "stdio"]`. It is recommended to still start `run_server.py` from the repository root. If a client can only be configured to a package directory and directly run a compatible entry, the current version also supports the following alternative writing:
```toml
[mcp_servers.allcanuse]
type = "stdio"
command = "/opt/homebrew/bin/python3"
args = ["stdio_compat.py", "--transport", "stdio", "--profile", "codex"]
cwd = "/Users/you/path/to/allcanuse-mcp/src/allcanuse_mcp"
enabled = true
startup_timeout_ms = 30000
tool_timeout_sec = 240
```
If you have executed `pip install -e .`, you can also change it to:
```toml
[mcp_servers.allcanuse]
type = "stdio"
command = "allcanuse-mcp"
enabled = true
startup_timeout_ms = 30000
tool_timeout_sec = 180
```
#### Claude Code
The common practice in the project is to write `.mcp.json` in the repository root:
```json
{
"mcpServers": {
"allcanuse": {
"type": "stdio",
"command": "python",
"args": ["run_server.py", "--transport", "stdio"],
"env": {}
}
}
}
```
If you have installed it as a command-line entry, you can also:
```json
{
"mcpServers": {
"allcanuse": {
"type": "stdio",
"command": "allcanuse-mcp",
"args": [],
"env": {}
}
}
}
```
#### OpenCode
OpenCode usually writes in the `mcp` field of `opencode.json` or `opencode.jsonc` in the `.config/opencode` directory of the user's directory:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"allcanuse": {
"type": "local",
"command": ["python", "D:/*****/allcanuse/run_server.py", "--transport", "stdio"],
"enabled": true
}
}
}
```
If you have installed it as a command-line entry, you can also:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"allcanuse": {
"type": "local",
"command": ["allcanuse-mcp"],
"enabled": true
}
}
}
```
#### LM Studio
In LM Studio's `mcp.json`, you can write:
```json
{
"mcpServers": {
"allcanuse": {
"command": "python",
"args": ["run_server.py", "--transport", "stdio"],
"cwd": "D:/path/to/allcanuse"
}
}
}
```
If you have installed it as a command-line entry, you can also:
```json
{
"mcpServers": {
"allcanuse": {
"command": "allcanuse-mcp",
"args": []
}
}
}
```
### 2.1 More client configuration format references
The following formats are based on the common configuration structures in the relevant authoritative client access documentation and rewritten into examples that can be directly used by `allcanuse-mcp`.
#### GitHub Copilot CLI
The MCP configuration file for GitHub Copilot CLI is usually:
```text
~/.copilot/mcp-config.json
```
If you have executed `pip install -e .`, it is recommended to write it directly as:
```json
{
"mcpServers": {
"allcanuse": {
"command": "allcanuse-mcp"
}
}
}
```
If you prefer to run directly from the repository directory, you can also write:
```json
{
"mcpServers": {
"allcanuse": {
"command": "python",
"args": ["run_server.py", "--transport", "stdio"],
"cwd": "D:/path/to/allcanuse"
}
}
}
```
#### GitHub Copilot IDEs
The common structure in GitHub Copilot IDE documentation is a project-level or user-level `.mcp.json` using the `servers` field.
If you have installed it as a command-line entry, it is recommended to write:
```json
{
"servers": {
"allcanuse": {
"type": "stdio",
"command": "allcanuse-mcp"
}
}
}
```
If your specific IDE version supports local commands with parameters, you can also change it to:
```json
{
"servers": {
"allcanuse": {
"type": "stdio",
"command": "python",
"args": ["run_server.py", "--transport", "stdio"]
}
}
}
```
#### Cursor
The common global MCP configuration file for Cursor is:
```text
~/.cursor/mcp.json
```
Recommended example:
```json
{
"mcpServers": {
"allcanuse": {
"command": "python",
"args": ["run_server.py", "--transport", "stdio"],
"cwd": "D:/path/to/allcanuse"
}
}
}
```
If you have installed it as a command-line entry, you can also:
```json
{
"mcpServers": {
"allcanuse": {
"command": "allcanuse-mcp"
}
}
}
```
#### Windsurf
The common MCP configuration file for Windsurf is:
```text
~/.codeium/windsurf/mcp_config.json
```
Recommended example:
```json
{
"mcpServers": {
"allcanuse": {
"command": "python",
"args": ["run_server.py", "--transport", "stdio"],
"cwd": "D:/path/to/allcanuse"
}
}
}
```
If you have installed it as a command-line entry, you can also:
```json
{
"mcpServers": {
"allcanuse": {
"command": "allcanuse-mcp"
}
}
}
```
#### Rovo Dev CLI
The common practice for Rovo Dev CLI is to run:
```text
acli rovodev mcp
```
Open the corresponding MCP configuration, and then write this project according to the same `mcpServers` structure. Recommended example:
```json
{
"mcpServers": {
"allcanuse": {
"command": "python",
"args": ["run_server.py", "--transport", "stdio"],
"cwd": "D:/path/to/allcanuse"
}
}
}
```
If you have installed it as a command-line entry, you can also:
```json
{
"mcpServers": {
"allcanuse": {
"command": "allcanuse-mcp"
}
}
}
```
### 3. Direct use after restarting the client
After saving the configuration, restart the corresponding client.
After successful connection, it is recommended to let the model call:
```text
list_all_tools()
```
And then let the model call:
```text
get_system_info()
get_desktop_context()
```
If these calls return normally, it usually indicates that MCP is connected and can be used directly.
### 4. `stdio` Access Exception Troubleshooting
In a few environments, you may encounter an unusual `stdio` access failure:
- The client configuration appears to be correct, and the server process can be started.
- The model side calls the tool and gets an empty result, or it waits for a response during the initialization phase.
- Manual testing of the server's stderr shows a similar `Invalid JSON: expected value`, and the input content looks like `Content-Length: 172`.
This is usually not a tool registration failure, but rather a mismatch between the client and the current Python MCP SDK on the `stdio` message format. Some clients send JSON-RPC messages in a framing format like `Content-Length: ...\r\n\r\n{json}`, while some SDK versions read stdin by default, one JSON per line, causing it to parse `Content-Length: ...` as the JSON body.
The current project's `--transport stdio` has been adapted to:
- Continue to support the original line-by-line JSON input and output.
- Also support `Content-Length` framing input and output.
- The server automatically selects the response format based on the client's actual first message format.
If a machine shows a situation where "other macOS / Windows / Linux are normal, but the current machine's call result is blank", it is recommended to troubleshoot in the following order:
1. Confirm that the client configuration still uses `--transport stdio`.
2. Update to a version that includes `src/allcanuse_mcp/stdio_compat.py`.
3. Completely restart the MCP client to let it restart the server process.
4. Call `list_all_tools()` first, then call a simple tool like `get_system_info()`.
5. If it is still abnormal, use the minimum stdio client to test line-by-line JSON and `Content-Length` framing separately.
## Documentation
- General usage instructions: [docs/USAGE.md](./docs/USAGE.md)
- Overview of all tools: [docs/TOOLS.md](./docs/TOOLS.md)
- On-duty workflow instructions: `resource://guides/workflows/duty-watch`
- LM Studio integration tutorial: [docs/LM-STUDIO.md](./docs/LM-STUDIO.md)
- Codex / Claude Code / OpenCode integration tutorial: [docs/CLIENT-INTEGRATIONS.md](./docs/CLIENT-INTEGRATIONS.md)
- Final user usage tutorial after release: [docs/RELEASE-USAGE.md](./docs/RELEASE-USAGE.md)
If you want to connect the current MCP to different clients, it is recommended to look at:
- [LM Studio](./docs/LM-STUDIO.md)
- [Full tool list](./docs/TOOLS.md)
- [ChatGPT Codex / Codex CLI](./docs/CLIENT-INTEGRATIONS.md)
- [Claude Code](./docs/CLIENT-INTEGRATIONS.md)
- [OpenCode](./docs/CLIENT-INTEGRATIONS.md)
- [Final user installation and integration after release](./docs/RELEASE-USAGE.md)
## Optional Dependencies
- Camera functionality prefers `opencv-python`, Linux can also fall back to `ffmpeg`, `libcamera-still`, `fswebcam`, Windows can also fall back to `ffmpeg`.
- Screenshot capability on Windows depends on `Pillow` by default.
- Windows process, port, and system information enhancements depend on `psutil` and `pywin32`.
- Linux window enumeration depends on `wmctrl`.
- Linux active window query depends on `xprop`.
- Linux screenshot may use `gnome-screenshot`, `scrot`, or `imagemagick`.
Supplement:
- Linux can still work with core system information, process query, port query, listening port, and established connection through the underlying `/proc` and `/sys` fallback even without installing `psutil`.
- Linux screenshot, window enumeration, foreground window query, and camera capabilities still mainly depend on the system graphics environment or additional tools; camera enumeration also supports directly reading `/dev/video*` and `/sys/class/video4linux`.
About how to pass images to the model:
- `capture_screenshot` and `capture_camera_photo` now not only return the local file path.
- If `return_image_content=true` is called, in MCP clients that support visual content, the tool result will directly include the image content, and the model can directly see the image.
- If the client does not support image content for the time being, the tool will still return structured metadata and local path, and can continue to read, upload, analyze, or pass it to other visual-enabled links.
## Verification
```powershell
python -m compileall src tests run_server.py
$env:PYTHONPATH=(Resolve-Path .\src).Path
python -m unittest discover -s tests -v
```
