# SecurityMCP-Ollama

A separate Ollama version of [NetskopeScripter12/SecurityMCP](https://github.com/NetskopeScripter12/SecurityMCP), based on commit `82bd58b40ec5fb57effa2c2618895e0a5410473c`.

Chat with a local model, retrieve the bundled demonstration documents, and run `/security+` or `/format` using MCP (Model Context Protocol). Includes an authenticated HTTP API and the original interactive CLI. No Anthropic/OpenAI SDK, paid-provider API key, cloud fallback, or automatic model downloads.

## Start on your machine

Install [Ollama](https://ollama.com/download) and Python 3.11 or newer. Start the Ollama app, or run `ollama serve` in another terminal if no server is running. Download the default tool-capable model once:

```bash
ollama pull qwen3:8b
```

Extract this folder (you MUST use the .zip file), open a terminal inside it, and run:

```bash
python -m venv .venv
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e '.[dev]'
python configure.py
python -m uvicorn api:app --host 127.0.0.1 --port 8000
```

`configure.py` generates `.env` with a random **application API token**. This is your own local authentication token, not a paid service key. It never overwrites an existing `.env`.

In a second terminal with the same virtual environment activated:

```bash
python test_api.py
```

That submits `/security+ urgent_memo.txt` to the actual running application and displays the response. To ask a different question:

```bash
python test_api.py --message 'Summarize @q3_roadmap.md'
```

**Your test endpoint after starting the app:** `POST http://127.0.0.1:8000/v1/chat`

**Interactive API documentation:** http://127.0.0.1:8000/docs

Click **Authorize**, paste the `SECURITYMCP_API_KEY` value from `.env`, then try `/v1/chat`. Do not paste the token into chat or commit `.env`.

Example request body:

```json
{"message":"/security+ urgent_memo.txt","allow_edits":false}
```

Example response shape (model wording varies):

```json
{"reply":"# Security Scan Report: urgent_memo.txt\n..."}
```

For curl, first set `SECURITYMCP_API_KEY` in your terminal to the generated token:

```bash
curl http://127.0.0.1:8000/v1/chat \
  -H "Authorization: Bearer $SECURITYMCP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"message":"Explain prompt injection briefly."}'
```

## Configuration

| Setting | Default | Meaning |
| --- | --- | --- |
| `OLLAMA_HOST` | `http://127.0.0.1:11434` | Base URL of your Ollama server, without `/api` or `/v1` |
| `OLLAMA_MODEL` | `qwen3:8b` | Installed model with tool-calling support |
| `SECURITYMCP_API_KEY` | Generated by `configure.py` | Protects the application HTTP API; not required for CLI |

Restart the application after changing `.env`. You can choose another downloaded tool-capable model by changing `OLLAMA_MODEL`. Models without tool support will not work with this agent. Model quality, latency, RAM and VRAM requirements vary; the `qwen3:8b` download is about 5.2 GB, with additional memory required at runtime.

Local inference has no per-call provider fee; it uses your own hardware and electricity. Prompts remain local with the default host and a local model. Setting a remote host, selecting a cloud model, or adding external MCP servers changes that data boundary. For Ollama local-only mode, set `OLLAMA_NO_CLOUD=1` **on the Ollama server process** and restart it, or use Ollama's `disable_ollama_cloud` setting. Adding that variable only to this app's `.env` will not configure an already-running Ollama server.

## CLI and document tools

```bash
python main.py
# Enable document writes explicitly:
python main.py --allow-edits
# Optional trusted Python MCP server scripts:
python main.py /absolute/path/to/another_mcp_server.py
```

Examples:

```text
Summarize @q3_roadmap.md
/security+ urgent_memo.txt
/format q3_roadmap.md
```

`/format` may propose an edit in read-only mode; start with `--allow-edits` to let it modify the demo document. In the HTTP API, set `allow_edits: true` on that request to enable edits. The flag is enforced by the tool router, independently of model instructions. Extension scripts are trusted local code, not sandboxed; only load scripts you trust. Read-only annotations for extensions are declarations from those trusted servers.

The HTTP endpoint is single-turn: every request starts an isolated MCP subprocess. Demo document edits last only within that request. CLI edits and conversation history last until the process exits. There is no persistent storage or shared HTTP conversation history.

## Scope and limitations

This preserves the source project's in-memory **document-security demo**. It does not scan your disk, inspect network devices, or produce compliance certifications. The original sample documents deliberately contain inert attack strings. They are never executed by the built-in document tools.

The original tool descriptions ask the model to block malicious content; these instructions are **not a deterministic malware filter or access-control boundary**. The underlying resources return document text. The local model can read suspicious strings to analyze them, and it can make mistakes. The added system instructions treat returned content as untrusted data.

The application sends bounded prompts to native Ollama `/api/chat`, validates function arguments against MCP schemas, returns errors for unknown/disallowed tools, preserves assistant thinking and tool-call messages between rounds, and limits tool rounds to eight. Failed turns are not committed to CLI history, but completed edits cannot be rolled back by a later model failure. For long conversations, restart the CLI to clear history; there is no automatic context compaction.

The API is intended for local testing: bearer authentication, two simultaneous requests, a 32,000-character message limit, 120-second model-call timeout and 300-second total request deadline. `/health` reports application liveness only; it does not prove Ollama/model readiness. There is no durable per-user quota system. Keep the default loopback binding; remote hosting needs HTTPS and deployment-specific access controls. Raw Ollama and the stdio MCP server do not use the application bearer token.

HTTP errors: `401` invalid token; `400` invalid command/document; `422` invalid body or tool-round limit; `429` busy; `503` Ollama unreachable; `502` missing model, unsupported tools, invalid response, or MCP failure; `504` timeout.

## Docker (optional; recipe not executed in this environment)

With Ollama running on your host:

```bash
python configure.py
docker build -t securitymcp-ollama .
docker run --rm -p 127.0.0.1:8000:8000 --env-file .env \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  --add-host=host.docker.internal:host-gateway securitymcp-ollama
```

Container-to-host connectivity depends on OS and Ollama's bind address. On Linux, an alternative is host networking with an explicit loopback bind for the app:

```bash
docker run --rm --network host --env-file .env securitymcp-ollama \
  uvicorn api:app --host 127.0.0.1 --port 8000
```

## Tests

```bash
python -m pytest -q
```

Tests use **real MCP subprocesses and mocked Ollama HTTP responses**. They cover the complete HTTP → model tool call → MCP → model answer path, authentication, input bounds, mutation opt-in, malformed arguments, duplicate tool names, MCP errors, document resources/prompts, loop limits, and model error handling. No model download or provider key is needed. Live Ollama inference and Docker execution were not tested in the build environment.

`CHANGE_REVIEW.html` shows additions and changed code in bright purple relative to the source repository. The source `.env`, generated bytecode, and old package metadata were not copied.

## Publish as a separate GitHub repo

No remote repository has been created by this package. The connected GitHub interface in this session supports editing repositories but not creating one. Create an empty `NetskopeScripter12/SecurityMCP-Ollama` repository and give its URL to the assistant to upload this version, or use GitHub CLI yourself:

```bash
git init -b main
git add .
git commit -m "Add native Ollama support and authenticated test API"
gh repo create NetskopeScripter12/SecurityMCP-Ollama --private --source=. --remote=origin --push
```

Run these commands inside this extracted folder, not inside the original SecurityMCP checkout. `.env` is ignored. The original repository is unaffected. The original CC0 license is retained.

## Protocol references

- [Ollama tool calling](https://docs.ollama.com/capabilities/tool-calling)
- [Native chat API](https://docs.ollama.com/api/chat)
- [Qwen3:8b model](https://ollama.com/library/qwen3:8b)
- [Ollama FAQ and local-only configuration](https://docs.ollama.com/faq)