192 lines
4.0 KiB
Markdown
192 lines
4.0 KiB
Markdown
# WebAccess.MCP Quick Start
|
|
|
|
Use this guide when the computer already has:
|
|
|
|
- Podman Desktop with a running Podman machine.
|
|
- Podman Compose.
|
|
- LM Studio 0.3.17 or later.
|
|
- A tool-capable model installed in LM Studio.
|
|
- Git.
|
|
|
|
All commands in this quick-start use **PowerShell (Standard user)**. Do not run
|
|
PowerShell as an administrator for this workflow.
|
|
|
|
## 1. Clone the Repository
|
|
|
|
**PowerShell (Standard user)**
|
|
|
|
```powershell
|
|
$McpRoot = Join-Path $env:SystemDrive "ai\mcp"
|
|
New-Item -ItemType Directory -Force -Path $McpRoot | Out-Null
|
|
Set-Location $McpRoot
|
|
git clone <repository-url> WebAccess.MCP
|
|
Set-Location ".\WebAccess.MCP"
|
|
```
|
|
|
|
Replace `<repository-url>` with the repository URL supplied by the project
|
|
owner.
|
|
|
|
`$env:SystemDrive` uses the Windows system drive, which is normally `C:`. The
|
|
resulting default repository location is:
|
|
|
|
```text
|
|
C:\ai\mcp\WebAccess.MCP
|
|
```
|
|
|
|
To use another local drive, set `$McpRoot` explicitly before cloning:
|
|
|
|
**PowerShell (Standard user)**
|
|
|
|
```powershell
|
|
$McpRoot = "E:\ai\mcp"
|
|
```
|
|
|
|
## 2. Start the Entire Stack
|
|
|
|
From the cloned repository root, run one command:
|
|
|
|
**PowerShell (Standard user)**
|
|
|
|
```powershell
|
|
.\Start-WebAccessMcp.cmd
|
|
```
|
|
|
|
The command:
|
|
|
|
1. Verifies Podman and Podman Compose.
|
|
2. Creates local installation secrets if they do not exist.
|
|
3. Builds the WebAccess.MCP container image.
|
|
4. Starts PostgreSQL, SearXNG, and WebAccess.MCP.
|
|
5. Displays container status and the local endpoint.
|
|
|
|
The first build can take several minutes.
|
|
|
|
If an earlier startup created failed or incomplete containers, running the same
|
|
command again replaces them with the corrected stack.
|
|
|
|
When startup succeeds, the MCP endpoint is:
|
|
|
|
```text
|
|
http://127.0.0.1:28081/mcp
|
|
```
|
|
|
|
The startup command does not report success until this health endpoint responds:
|
|
|
|
```text
|
|
http://127.0.0.1:28081/health
|
|
```
|
|
|
|
## 3. Add WebAccess.MCP to LM Studio
|
|
|
|
1. Open LM Studio.
|
|
2. Open the **Program** tab in the right sidebar.
|
|
3. Select **Install > Edit mcp.json**.
|
|
4. Add `webaccess` inside the existing `mcpServers` object.
|
|
|
|
For an empty configuration, use:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
If other MCP servers already exist, preserve them and add:
|
|
|
|
```json
|
|
"webaccess": {
|
|
"url": "http://127.0.0.1:28081/mcp"
|
|
}
|
|
```
|
|
|
|
Include a comma between server entries. Do not add `command`, `args`, headers,
|
|
or a Podman path to the `webaccess` entry.
|
|
|
|
5. Save `mcp.json`.
|
|
6. Click **Refresh** in LM Studio.
|
|
7. Confirm that `webaccess` is connected and exposes 15 tools.
|
|
|
|
## 4. Test It
|
|
|
|
Load the tool-capable model and ask:
|
|
|
|
> Use `web_search` to find the official LM Studio MCP documentation and return
|
|
> the source URL.
|
|
|
|
LM Studio should display a `web_search` tool call.
|
|
|
|
## Normal Startup After a Restart
|
|
|
|
Start Podman Desktop and its Podman machine, then run from the repository root:
|
|
|
|
**PowerShell (Standard user)**
|
|
|
|
```powershell
|
|
.\Start-WebAccessMcp.cmd
|
|
```
|
|
|
|
The command is safe to run again. It preserves the existing secrets and
|
|
PostgreSQL page cache.
|
|
|
|
## Stop the Stack
|
|
|
|
From the repository root:
|
|
|
|
**PowerShell (Standard user)**
|
|
|
|
```powershell
|
|
Set-Location ".\deploy"
|
|
podman compose --project-name webaccess-mcp stop
|
|
```
|
|
|
|
## If Startup Fails
|
|
|
|
Check Podman:
|
|
|
|
**PowerShell (Standard user)**
|
|
|
|
```powershell
|
|
podman info
|
|
podman compose version
|
|
```
|
|
|
|
Check the stack:
|
|
|
|
**PowerShell (Standard user)**
|
|
|
|
```powershell
|
|
Set-Location ".\deploy"
|
|
podman compose --project-name webaccess-mcp ps --all
|
|
podman compose --project-name webaccess-mcp logs --tail 200
|
|
```
|
|
|
|
Test the HTTP server itself:
|
|
|
|
**PowerShell (Standard user)**
|
|
|
|
```powershell
|
|
Invoke-RestMethod "http://127.0.0.1:28081/health"
|
|
```
|
|
|
|
Expected result:
|
|
|
|
```text
|
|
status
|
|
------
|
|
healthy
|
|
```
|
|
|
|
Do not use a plain browser request or `curl` GET to `/mcp` as the health test.
|
|
`/mcp` expects MCP protocol requests and can return a protocol or method error
|
|
even when the server is reachable. Use `/health` to test connectivity and LM
|
|
Studio to test the MCP handshake.
|
|
|
|
For detailed instructions, see:
|
|
|
|
- `docs\Standing-Up-the-Podman-Compose-Stack.md`
|
|
- `docs\Adding-WebAccess-MCP-to-LM-Studio.md`
|