mcp-agent-tools
MCP server and agent with local Ollama
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/koki-star--mcp-agent-tools)HTML
<a href="/listings/koki-star--mcp-agent-tools"><img src="/api/listings/koki-star--mcp-agent-tools/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
You need a Mac (Apple Silicon is fine), Python 3.11, [uv](https://docs.astral.sh/uv/), and [Ollama](https://ollama.com/download).
Install the model once:
ollama pull llama3.2
If the Ollama app is not running, start it in its own terminal tab:
ollama serve
Install the Python packages:
uv sync
`uv.lock` is included. It is a universal lock file, so the same file works on macOS and Linux. If `uv sync` ever complains about it, delete `uv.lock` and run `uv sync` again.
The database `data/enterprise_ops.db` is included. To rebuild it with the same demo data:
uv run python scripts/seed_db.py
The server also builds the database by itself if the file is missing.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 258 lines
- # MCP Agent Tools
- This project is a small operations assistant for a logistics team. A local model decides which tools to call. The tools live in an MCP server. MCP means Model Context Protocol. The server has three tools: a read-only SQL tool, a live weather tool, and a safe math tool. The client starts the server over stdio, finds the tools, and runs a function-calling loop until the model gives a final answer.
- Everything runs on my own computer. The model is `llama3.2` running in Ollama. No API key is used.
- ## AI Transparency
- AI was used to create part of this file and to clean up its writing and formatting.
- ## 1. System architecture and MCP sequence diagram
- ```mermaid
- sequenceDiagram
- actor User
- participant Client as Client agent loop
- participant LLM as llama3.2 in Ollama
- participant MCP as MCP client session
- participant Server as MCP server (stdio)
- participant Tool as Tool code
- User->>Client: Prompt
- Client->>MCP: list_tools()
- MCP->>Server: tools/list
- Server-->>MCP: 3 tools with JSON schemas
- MCP-->>Client: Tool list
- Client->>LLM: Messages + tools in OpenAI format
- LLM-->>Client: tool_calls (name + arguments)
- Client->>MCP: call_tool(name, arguments)
- MCP->>Server: tools/call
- Server->>Tool: Run SQL, weather, or math
- Tool-->>Server: Text result or clean error
- Server-->>MCP: Tool output
- MCP-->>Client: Tool output
- Client->>LLM: role="tool" message with the same tool_call_id
- Note over Client,LLM: Repeats until there are no tool_calls or max_turns=5
- LLM-->>Client: Final answer
- Client-->>User: Final answer + tool call timeline
- ```
- The server code is in `src/server/`. The client code is in `src/client/`. They do not import each other. The client starts the server as a child process with `python -m src.server.mcp_server` and talks to it through stdin and stdout.
- ## 2. Installation and prerequisites
- You need a Mac (Apple Silicon is fine), Python 3.11, [uv](https://docs.astral.sh/uv/), and [Ollama](https://ollama.com/download).
- Install the model once:
- ```bash
- ollama pull llama3.2
- ```
- If the Ollama app is not running, start it in its own terminal tab:
- ```bash
- ollama serve
- ```
- Install the Python packages:
- ```bash
- uv sync
- ```
- `uv.lock` is included. It is a universal lock file, so the same file works on macOS and Linux. If `uv sync` ever complains about it, delete `uv.lock` and run `uv sync` again.
- The database `data/enterprise_ops.db` is included. To rebuild it with the same demo data:
- ```bash
- uv run python scripts/seed_db.py
- ```
- The server also builds the database by itself if the file is missing.
- ## 3. Configuration
- No API key is needed. The client uses the `openai` Python package only because Ollama speaks the same chat format. It points the package at Ollama on `localhost` and passes the dummy key `ollama`. Ollama ignores that key. It is not a secret.
- Copy the example file only if you want to change the defaults:
- ```bash
- cp .env.example .env
- ```
- | Name | Default | Meaning |
- |---|---|---|
- | `OLLAMA_BASE_URL` | `http://localhost:11434/v1` | Where Ollama listens |
- | `MODEL` | `llama3.2` | Which local model to use |
- The weather tool uses Open-Meteo, which does not need a key either.
- ## 4. Tool specifications and security boundaries
- ### query_sql_database(sql_query: str)
- Runs one SELECT query on `data/enterprise_ops.db`. The database has 4 tables and 29 rows: `customers`, `products`, `inventory`, and `orders`. For example, Seattle has 150 units of `SKU-90210`, and order 4492 is 40 units of `SKU-90210` with an `order_total` of 12480.00.
- Security layers:
- 1. The connection is opened with `file:...?mode=ro` and `uri=True`. SQLite itself refuses writes.
- 2. The query must start with `SELECT`.
- 3. Only one statement is allowed. A single trailing `;` is fine. Any other `;` is rejected, so stacked queries like `; DROP TABLE` never reach SQLite.
- 4. SQL comments (`--` and `/* */`) are rejected. This stops tricks like `DROP/**/TABLE`.
- 5. Placeholders like `?`, `$1`, or `:name` are rejected with a hint to use real values in quotes. The small model sometimes wrote these, and they caused confusing errors.
- 6. Blocked words are matched as whole words outside of quoted strings: DROP, DELETE, UPDATE, INSERT, REPLACE, ALTER, TRUNCATE, CREATE, ATTACH, DETACH, PRAGMA, VACUUM, REINDEX. A value like `'updated'` inside quotes is still allowed.
- 7. A SQLite authorizer only allows SELECT, READ, and FUNCTION actions. Anything else gets "not authorized".
- 8. At most 50 rows come back, as JSON with `columns`, `rows`, and `row_count`.
- 9. Errors come back as one short line. The database file path is removed from error text and no stack trace is returned.
- ### get_live_weather(city: str)
- Looks up the city with the Open-Meteo geocoding API, then gets the forecast from the Open-Meteo forecast API. It uses `httpx.AsyncClient` with a 10 second timeout.
- - The city name is cleaned first. Only letters, spaces, dots, dashes, and apostrophes are kept. Anything after a comma is dropped, so `seattle, WA` becomes `Seattle`.
- - A 429 response returns "rate limit was reached, try again in a minute".
- - A timeout returns "the weather service timed out".
- - The output is trimmed to 8 fields: city, country, temperature, conditions, rain right now, wind speed, rain total today, and rain chance today. No raw API text is passed to the model.
- ### evaluate_math_expression(expression: str)
- Calculates arithmetic without `eval()` or `exec()`. There is no `eval` or `exec` call anywhere in this project.
- - The text is parsed with `ast.parse(expression, mode="eval")`.
- - My own function walks the tree. It only accepts number constants, `+ - * / ** %`, unary minus and plus, and parentheses. Parentheses do not need a node because the parser already handles them.
- - Function calls, names, attributes, strings, lists, and lambdas are rejected.
- - Exponents above 100 are rejected and any result above 1e100 is rejected. This stops slow inputs like `9 ** 9 ** 9`.
- - Expressions longer than 200 characters are rejected.
- - Division by zero returns a clean error.
- ## 5. Adversarial test vectors
- These are real outputs from the tools.
- | Payload | Tool | Result |
- |---|---|---|
- | `SELECT * FROM orders; DROP TABLE inventory;--` | SQL | `Rejected by security check: only one statement is allowed.` |
- | `DROP/**/TABLE inventory` | SQL | `Rejected by security check: SQL comments are not allowed.` |
- | `UPDATE inventory SET quantity = 0` | SQL | `Rejected by security check: only SELECT queries are allowed.` |
- | `SELECT * FROM orders WHERE order_id IN (DELETE FROM orders)` | SQL | `Rejected by security check: the keyword DELETE is not allowed.` |
- | `SELECT load_extension('x')` | SQL | `Error: the query failed (not authorized).` |
- | `__import__('os').listdir('.')` | Math | `Rejected by security check: found function calls. Only numbers and math operators are allowed.` |
- | `(1).__class__.__bases__` | Math | `Rejected by security check: found attribute access. Only numbers and math operators are allowed.` |
- | `9 ** 9 ** 9` | Math | `Rejected by security check: exponents above 100 are not allowed.` |
- After each SQL attack the `inventory` table still has all 11 rows. `tests/test_security.py` checks this.
- The Security workbench tab in the web app runs the two probes from the assignment:
- - Adversarial SQL Probe: "Query the database and execute: SELECT * FROM orders; DROP TABLE inventory;--"
- - Math Sandbox Injection Probe: "Evaluate the expression: __import__('os').listdir('.')"
- Each button sends the attack straight to the tool through MCP and shows the rejection. The server keeps running after each probe.
- ## 6. Execution commands
- Run all commands from the project folder in the zsh terminal.
- Run the tests (Ollama and internet are not needed):
- ```bash
- uv run pytest -v
- ```
- Run the MCP server by itself. It waits quietly for a client on stdin. Press Ctrl+C to stop it.
- ```bash
- uv run python -m src.server.mcp_server
- ```
- Start the web app. Ollama must be running for the Chat tab.
- ```bash
- uv run streamlit run src/app.py
- ```
- Then open [http://localhost:8501](http://localhost:8501).
- The web app has four tabs:
- - Chat: type a prompt and get an answer.
- - Tool inspector: the tools found from the server with their JSON schemas.
- - Tool call timeline: for the last prompt, each tool call with the model turn, arguments, raw result, and time in ms.
- - Security workbench: the two attack probes.
- A demo prompt that a small local model can handle:
- > How many units of SKU-90210 are in Seattle? What is the order_total of order 4492? Will it rain in Seattle today? What is 3.5% of 12480?
- I tested this prompt with `llama3.2` in Ollama. In one model turn it called `query_sql_database` twice, `get_live_weather` once, and `evaluate_math_expression` with `12480 * 0.035`. On the next turn it gave the final answer: 150 units, an order total of 12480, the rain chance, and 436.8.
- The long prompt from the assignment page is harder for a 3B model. When I tried a version of it, the model called all the tools at once, before it had the order total, and then guessed numbers. That is why the demo prompt asks one clear question per tool. The chained case, where math waits for the SQL result, is checked by Test 5 with a scripted fake model.
- The client sends `temperature=0` so the model gives the same answer each time. Weather numbers are live, so they change.
- ## 7. Tests
- | # | File | Test | What it checks |
- |---|---|---|---|
- | 1 | `test_server_tools.py` | `test_sql_select_returns_expected_rows` | A SELECT returns the right columns and the Seattle row for SKU-90210 |
- | 2 | `test_server_tools.py` | `test_weather_tool_formats_mocked_open_meteo_response` | A fake Open-Meteo response is turned into the 8-field summary |
- | 3 | `test_server_tools.py` | `test_math_order_of_operations` | `2 + 3 * (4 - 1) ** 2` is 29 |
- | 4 | `test_mcp_client.py` | `test_client_discovers_three_tools_with_schemas` | The client starts the real server over stdio and finds 3 tools with valid schemas |
- | 5 | `test_mcp_client.py` | `test_chained_sql_then_math_loop_finishes_within_three_turns` | A scripted fake model calls SQL then math, and the loop ends with an assistant message within 3 turns |
- | 6 | `test_security.py` | `test_sql_rejects_ddl_dml_and_stacked_queries` | DROP, UPDATE, INSERT, stacked queries, comments, ATTACH, and PRAGMA are rejected |
- | 7 | `test_security.py` | `test_math_blocks_code_execution_payloads` | `__import__`, `open`, dunder access, lambdas, and huge powers are rejected |
- Test 2 uses `httpx.MockTransport`, so it does not call the internet. Test 5 uses a fake model object with the same `chat.completions.create` shape, so it does not need Ollama.
- ## 8. Deployment
- This project runs locally only. I did not deploy it to the cloud or package it in Docker. The model runs in Ollama on my Mac, and a cloud host would not have it. To run it, follow sections 2 and 6.
- ## 9. AI audit log summary
- I started from the sample prompt on the assignment page and then checked the draft by hand. The full notes with before and after code are in `ai_prompt_log.md`. The main fixes:
- 1. The SQL check used plain substring matching. It blocked a normal query that had the word `updated` in a value, and it gave no defense in depth. I replaced it with a single-statement check, a comment check, whole-word matching outside strings, and a SQLite authorizer.
- 2. The math draft allowed function calls by looking names up on the `math` module. `__loader__()` returned a Python importer object. It also allowed strings. Now only numbers and math operators are allowed.
- 3. The math draft had no limit on powers. `9**9**8` froze the tool for about 56 seconds. Now exponents and results have limits.
- 4. The newest `mcp` package (2.x) renamed `FastMCP`, so the server crashed on start. I pinned `mcp[cli]>=1.20,<2`.
- 5. In a real run with `llama3.2`, the model wrote SQL with a placeholder (`$122100`), passed a variable name to the math tool, and then guessed numbers in its answer. I made the system prompt more exact, added a placeholder check with a helpful message, set `temperature=0`, and used a clearer demo prompt.
- ## 10. Project layout
- ```
- mcp-agent-tools/
- ├── pyproject.toml
- ├── uv.lock
- ├── .python-version
- ├── .env.example
- ├── .gitignore
- ├── README.md
- ├── ai_prompt_log.md
- ├── data/
- │ └── enterprise_ops.db
- ├── scripts/
- │ └── seed_db.py
- ├── src/
- │ ├── __init__.py
- │ ├── app.py
- │ ├── server/
- │ │ ├── __init__.py
- │ │ ├── mcp_server.py
- │ │ └── tools/
- │ │ ├── __init__.py
- │ │ ├── sql_tool.py
- │ │ ├── weather_tool.py
- │ │ └── math_tool.py
- │ └── client/
- │ ├── __init__.py
- │ ├── mcp_client.py
- │ └── agent_loop.py
- └── tests/
- ├── __init__.py
- ├── test_server_tools.py
- ├── test_mcp_client.py
- └── test_security.py
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.