# 🟦 mcp-toolkit-ts

<div align="center">

[![TypeScript CI](https://github.com/IsmeetPandey/mcp-toolkit-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/IsmeetPandey/mcp-toolkit-ts/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Language: TypeScript](https://img.shields.io/badge/Language-TypeScript-3178C6.svg)](https://www.typescriptlang.org/)
[![MCP Ready](https://img.shields.io/badge/MCP-Protocol%202024--11--05-brightgreen.svg)](https://modelcontextprotocol.io)

**Production-ready Model Context Protocol (MCP) server toolkit for autonomous AI agents with typed schemas and safety guardrails.**

</div>

---

## ⚡ Highlights

- **🔒 Strongly Typed Tools**: Define agent tools with parameter schemas and auto-generated JSON Schema manifests.
- **🤖 Agent Client Compatible**: Out-of-the-box support for Claude Desktop, Cursor, Antigravity, and OpenAI assistants.
- **🛡️ Parameter Validation**: Enforces parameter requirements, type safety, and error feedback before tool invocation.
- **🚀 Zero Bloat**: Minimal runtime footprint designed for fast cold starts.

---

## 📦 Installation

```bash
npm install mcp-toolkit-ts
```

---

## 💻 Quick Start

```typescript
import { MCPServer, ToolDefinition } from 'mcp-toolkit-ts';

const server = new MCPServer('my-agent-tools', '1.0.0');

// Register a custom typed tool
server.registry.register({
  name: 'calculate_growth',
  description: 'Calculate compounded interest rate for financial simulations',
  parameters: {
    principal: { type: 'number', description: 'Initial balance', required: true },
    rate: { type: 'number', description: 'Annual interest rate percentage', required: true },
    years: { type: 'number', description: 'Simulation duration in years', required: true },
  },
  handler: async ({ principal, rate, years }) => {
    return principal * Math.pow(1 + rate / 100, years);
  },
});

// Handle incoming MCP JSON-RPC call
const response = await server.handleRequest({
  method: 'tools/call',
  params: {
    name: 'calculate_growth',
    arguments: { principal: 1000, rate: 5, years: 3 }
  }
});

console.log('Result:', response); // 1157.625
```

---

## 📄 License

MIT License © 2026 [Ismeet Pandey](https://github.com/IsmeetPandey).