# MCP Toolkit Server

<p align="center">
  <strong>A Model Context Protocol server exposing custom tools — DB queries, API calls, file I/O, and more — for Claude and other AI agents.</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/MCP-1.0-blue" alt="MCP Protocol" />
  <img src="https://img.shields.io/badge/Node.js-18+-green" alt="Node.js" />
  <img src="https://img.shields.io/badge/TypeScript-5.x-blue" alt="TypeScript" />
  <img src="https://img.shields.io/badge/License-MIT-yellow" alt="License" />
</p>

---

## Overview

The **MCP Toolkit Server** is a production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that equips Claude, ChatGPT, and other LLM agents with a rich set of tools for interacting with databases, external APIs, the file system, and more — directly relevant to the **agentic AI wave**.

Built with TypeScript and the official `@modelcontextprotocol/sdk`, this server runs as a local stdio process and integrates seamlessly with Claude Desktop, the MCP Inspector, or any MCP-compatible client.

---

## Features & Tools

| Tool | Description | Example Use Case |
|------|-------------|-----------------|
| **`db_query`** | Execute SQL queries against SQLite (explore mode with demo DB or file mode) | "Show me all users who placed orders this month" |
| **`api_call`** | Make HTTP requests to any REST API with custom headers, params, and body | Fetch data from a weather API, send a webhook |
| **`file_read`** | Read file contents from the local filesystem | Read a config file, inspect a log |
| **`file_write`** | Write content to files (creates parent dirs automatically) | Save generated code, export data |
| **`file_list`** | List files/directories with optional recursive listing and filtering | Explore a project structure |
| **`calculator`** | Safely evaluate math expressions (no `eval`) | Calculate compound interest, unit conversions |
| **`get_datetime`** | Get current date/time with timezone support | Timestamp logging, scheduling |
| **`json_parser`** | Parse, validate, query, and summarize JSON data | Extract fields from API responses |
| **`text_transform`** | 17+ text operations: case conversion, slug, base64, extract emails/URLs, word count | Data cleaning, text normalization |
| **`get_environment`** | Get server environment info (OS, CPU, memory, Node.js version) | Debug, context awareness |

---

## Quick Start

### Prerequisites

- **Node.js** >= 18.0.0
- **npm** >= 9.0.0

### Installation

```bash
# Clone the repository
git clone https://github.com/vyshnavi-nandyala/mcp-toolkit-server.git
cd mcp-toolkit-server

# Install dependencies
npm install

# Build the TypeScript project
npm run build
```

### Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "toolkit": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-toolkit-server/dist/index.js"]
    }
  }
}
```

> Replace `/absolute/path/to/mcp-toolkit-server` with the actual path on your machine.

Restart Claude Desktop, and you'll see a 🔨 icon in the input area — your tools are ready!

### Using with MCP Inspector (Debugging)

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

This opens a web UI where you can manually test each tool, inspect request/response payloads, and debug issues.

---

## Usage Examples

### DB Query — Explore the Demo Database

Ask Claude:

> "Show me the top 5 products by price from the demo database."

Claude will use the `db_query` tool:

```json
{
  "sql": "SELECT name, category, price FROM products ORDER BY price DESC LIMIT 5"
}
```

### API Call — Fetch Weather Data

Ask Claude:

> "What's the current weather in San Francisco?"

Claude will use the `api_call` tool:

```json
{
  "url": "https://api.open-meteo.com/v1/forecast?latitude=37.7749&longitude=-122.4194&current_weather=true",
  "method": "GET"
}
```

### File Operations

Ask Claude:

> "List all TypeScript files in my project, then read the main entry point."

Claude will chain `file_list` → `file_read`:

```json
{ "dirPath": "/path/to/project", "extension": ".ts", "recursive": true }
{ "filePath": "/path/to/project/src/index.ts" }
```

### JSON Parsing

Ask Claude:

> "Parse this JSON and extract the first user's email: `{\"users\":[{\"email\":\"alice@example.com\"},{\"email\":\"bob@example.com\"}]}`"

```json
{
  "json": "{\"users\":[{\"email\":\"alice@example.com\"}]}",
  "operation": "query",
  "path": "users[0].email"
}
```

### Text Transform

Ask Claude:

> "Convert this to camelCase and slug: 'My Project Name'"

```json
{ "text": "My Project Name", "operation": "camelcase" }
// → "myProjectName"

{ "text": "My Project Name", "operation": "slug" }
// → "my-project-name"
```

---

## Architecture

```
mcp-toolkit-server/
├── src/
│   ├── index.ts                  # Entry point — creates and starts the MCP server
│   ├── tools/
│   │   ├── db-query.ts           # SQLite query tool (explore + file modes)
│   │   ├── api-call.ts           # HTTP request tool (fetch-based)
│   │   ├── file-operations.ts    # file_read, file_write, file_list
│   │   ├── calculator.ts         # Safe math expression evaluator
│   │   ├── datetime.ts           # Date/time with timezone support
│   │   ├── json-parser.ts        # Parse, query, validate, summarize JSON
│   │   ├── text-transform.ts     # 17+ text manipulation operations
│   │   └── environment.ts        # System environment info
│   └── utils/
│       └── helpers.ts            # Shared response-building utilities
├── tests/
│   └── tools.test.ts             # Unit tests (vitest)
├── package.json
├── tsconfig.json
└── README.md
```

### Design Principles

1. **Safety First** — SQL injection prevention, no `eval()`, read-only defaults for DB queries
2. **Modular** — Each tool is a self-contained module; easy to add/remove tools
3. **Typed** — Full TypeScript with Zod schemas for input validation
4. **Observable** — Structured JSON responses with metadata (timing, counts, types)
5. **Developer-Friendly** — MCP Inspector support, comprehensive README, unit tests

---

## Adding Custom Tools

Adding a new tool is straightforward:

```typescript
// src/tools/my-custom-tool.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function registerMyCustomTool(server: McpServer): void {
  server.tool(
    "my_custom_tool",
    "Description of what this tool does.",
    {
      param1: z.string().describe("First parameter."),
      param2: z.number().optional().describe("Optional second parameter."),
    },
    async ({ param1, param2 }) => {
      // Your logic here
      return {
        content: [
          { type: "text", text: JSON.stringify({ result: "..." }, null, 2) },
        ],
      };
    }
  );
}
```

Then register it in `src/index.ts`:

```typescript
import { registerMyCustomTool } from "./tools/my-custom-tool.js";
// ...
registerMyCustomTool(this.server);
```

---

## Development

```bash
# Run in development mode (no build step needed)
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Watch tests
npm run test:watch

# Lint
npm run lint
```

---

## Why This Matters: The Agentic AI Wave

MCP (Model Context Protocol) is the open standard that allows AI agents like Claude to interact with external tools, data sources, and services. Instead of being confined to a chat window, MCP servers give agents the ability to:

- **Query databases** with natural language
- **Call external APIs** to fetch real-time data
- **Read and write files** on the local filesystem
- **Perform computations** and data transformations
- **Compose multi-step workflows** by chaining tools together

This server is a concrete, production-ready implementation of that vision — a toolkit that transforms Claude from a conversational AI into an **actionable agent** capable of interacting with the real world.

---

## License

MIT License. See [LICENSE](./LICENSE) for details.