<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&height=220&text=MCP+Server+Toolkit&fontAlign=50&fontAlignY=40&color=timeGradient&customColorList=6,8,12,14,20&fontColor=ffffff&fontSize=36&animation=fadeIn" width="100%" />
</p>

<p align="center">
  <img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=600&size=22&pause=1000&color=9333EA&center=true&vCenter=true&multiline=true&repeat=true&width=700&height=120&lines=Production+MCP+Server+for+Claude+Desktop;8+Powerful+Tools+%7C+File+%2B+Shell+%2B+Web+%2B+AI;Drop-In+Config+for+Any+MCP+Client" alt="Typing SVG" />
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.11+-9333ea?style=for-the-badge&logo=python&logoColor=white" />
  <img src="https://img.shields.io/badge/MCP-Model+Context+Protocol-9333ea?style=for-the-badge&logo=anthropic&logoColor=white" />
  <img src="https://img.shields.io/badge/Anthropic-Claude+Sonnet-9333ea?style=for-the-badge&logo=anthropic&logoColor=white" />
  <img src="https://img.shields.io/badge/aiohttp-Async+Web-9333ea?style=for-the-badge&logo=aiohttp&logoColor=white" />
  <img src="https://img.shields.io/badge/DuckDuckGo-Search-9333ea?style=for-the-badge&logo=duckduckgo&logoColor=white" />
  <img src="https://img.shields.io/badge/License-MIT-9333ea?style=for-the-badge" />
</p>

---

## Overview

**MCP Server Toolkit** is a production-ready [Model Context Protocol](https://modelcontextprotocol.io) server that exposes 8 powerful tools to Claude Desktop and any MCP-compatible client. With a single config entry, Claude gains the ability to read and write files, run shell commands, search the web, fetch URLs, and perform AI-powered code reviews and text summarisation — all with built-in security controls.

---

## Features

| Tool | Description |
|---|---|
| `read_file` | Read file contents with size guard (10 MB limit) and encoding detection |
| `write_file` | Write / create files, restricted to CWD with auto parent-dir creation |
| `list_directory` | List directory with file types, sizes, and modified timestamps |
| `execute_shell` | Run shell commands against a strict allowlist with dangerous-pattern blocking |
| `web_search` | DuckDuckGo Instant Answer API — returns structured results with snippets and URLs |
| `fetch_url` | Fetch and parse any web page, strips nav/ads/scripts, returns clean text + links |
| `code_review` | Claude-powered code review with issues, severity ratings, security analysis, verdict |
| `summarise_text` | Claude-powered summarisation with key points, structured paragraphs, takeaway |

### Security Model

- **Path sanitisation**: Blocks `..` traversal, symlink abuse, and access to sensitive system files (`~/.ssh`, `~/.aws/credentials`, `/etc/shadow`, etc.)
- **Write isolation**: `write_file` is restricted to the current working directory
- **Command allowlist**: `execute_shell` only permits a curated set of safe commands (`ls`, `grep`, `git`, `python`, `curl`, etc.)
- **Pattern blocking**: Chains like `; rm`, `| sh`, fork bombs, and decode-and-exec patterns are rejected before execution
- **Output truncation**: Shell stdout/stderr capped at 512 KB; web content at 256 KB

---

## Architecture

```
mcp-server-toolkit/
│
├── server/
│   ├── main.py                  # MCP server — tool registration & dispatch
│   ├── security.py              # Path sanitisation + command allowlist
│   └── tools/
│       ├── __init__.py          # Re-exports all tool functions
│       ├── file_tools.py        # read_file, write_file, list_directory
│       ├── shell_tools.py       # execute_shell (with validation)
│       ├── web_tools.py         # web_search (DuckDuckGo), fetch_url (aiohttp + BS4)
│       └── ai_tools.py          # code_review, summarise_text (Claude API)
│
├── claude_desktop_config.json   # Drop-in config for Claude Desktop
├── requirements.txt
└── README.md
```

**Request flow:**

```
Claude Desktop  →  stdio transport  →  server/main.py (MCP Server)
                                              ↓ dispatch
                                   tools/file_tools.py   ← local filesystem
                                   tools/shell_tools.py  ← subprocess (allowlisted)
                                   tools/web_tools.py    ← aiohttp / DuckDuckGo
                                   tools/ai_tools.py     ← Anthropic Claude API
```

---

## Quick Start

### 1. Clone & Install

```bash
git clone https://github.com/isamkhan1809/mcp-server-toolkit
cd mcp-server-toolkit
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
```

### 2. Set Environment Variables

```bash
export ANTHROPIC_API_KEY="sk-ant-..."   # required for code_review + summarise_text
```

### 3. Test the Server

```bash
python -m server.main
```

The server communicates over stdio and is ready for MCP client connections.

### 4. Connect to Claude Desktop

Copy the following into your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcp-server-toolkit": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "/absolute/path/to/mcp-server-toolkit",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-your-key-here",
        "PYTHONPATH": "/absolute/path/to/mcp-server-toolkit"
      }
    }
  }
}
```

Restart Claude Desktop. You will see the toolkit listed under available tools.

---

## Project Structure

```
server/main.py          — MCP server, tool registration, call dispatcher
server/security.py      — sanitise_path(), validate_command(), blocked prefixes & patterns
server/tools/
  file_tools.py         — read_file, write_file, list_directory
  shell_tools.py        — execute_shell (subprocess + security gate)
  web_tools.py          — web_search (DuckDuckGo API), fetch_url (aiohttp + BeautifulSoup)
  ai_tools.py           — code_review, summarise_text (Claude claude-sonnet-4-5)
claude_desktop_config.json  — Ready-to-paste Claude Desktop config
requirements.txt
```

---

## Usage Examples

Once connected to Claude Desktop, you can ask Claude:

```
"Read the file ./src/main.py and review it for bugs"
→ calls read_file, then code_review

"Search for 'MCP protocol specification' and summarise the top result"
→ calls web_search, then fetch_url, then summarise_text

"List my project directory and show me what's in the src folder"
→ calls list_directory

"Run git status in my project"
→ calls execute_shell("git status")

"Write a new file called notes.md with today's meeting notes"
→ calls write_file
```

---

## Configuration

### Environment Variables

| Variable | Required | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | For AI tools | API key for `code_review` and `summarise_text` |

### Allowed Shell Commands

The following base commands are permitted by `execute_shell`:

```
ls  find  cat  head  tail  wc  file  stat  du  df
grep  awk  sed  sort  uniq  cut  tr  jq  diff
git  python  python3  pip  pip3  node  npm
pytest  ruff  mypy  black
echo  pwd  whoami  date  uname  env
curl  wget
```

To add a command, append it to `ALLOWED_COMMANDS` in `server/security.py`.

### Extending with New Tools

1. Add your function to the appropriate `server/tools/*.py` file
2. Export it from `server/tools/__init__.py`
3. Register a new `types.Tool` entry in `server/main.py`'s `list_tools()`
4. Add a dispatch branch in `call_tool()`

---

<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&height=120&section=footer&color=timeGradient&customColorList=6,8,12,14,20&animation=fadeIn" width="100%" />
</p>