# TaskBridge

An MCP (Model Context Protocol) server that lets Claude manage a task
list through natural language, connecting an AI model to a real,
persistent system instead of a one-off API call.

## Problem

An AI model that can only respond to text has limited practical use. Real
AI products need to read, write, and act on external systems - task
lists, calendars, files. MCP is the open standard Anthropic built to
let AI models connect to these systems safely and predictably.

## How It Works

TaskBridge exposes three tools to Claude: adding a task, listing tasks,
and marking a task complete. When Claude Desktop is configured with this
server, asking Claude in natural language ("add a task", "list my
tasks") triggers a real tool call, which reads and writes to a local
JSON file. Every tool call requires explicit user approval before it
runs.

## Tools

- **add_task(title)** - adds a new task to the list.
- **list_tasks()** - lists all tasks with their completion status.
- **complete_task(task_id)** - marks a task as complete by its ID.

## Tech Stack

- Python 3.14
- [MCP Python SDK](https://modelcontextprotocol.io/) (Model Context
  Protocol)
- Claude Desktop (as the MCP client)

## Setup

1. Clone the repository
2. Create and activate a virtual environment
3. Install dependencies
4. Add TaskBridge to your Claude Desktop config (`claude_desktop_config.json`):
```json
   "mcpServers": {
     "taskbridge": {
       "command": "/absolute/path/to/taskbridge/venv/bin/python3",
       "args": ["/absolute/path/to/taskbridge/server.py"]
     }
   }
```
5. Restart Claude Desktop completely, then check Settings > Developer to
   confirm the server shows as "running".

## Usage

In Claude Desktop, just ask naturally:
- "Add a task: finish the report"
- "List my tasks"
- "Mark task 1 as complete"

Claude will ask for your approval before each tool call.

## Example

**Prompt:** "Add a task: Finish the TaskBridge project README"
**Result:** `Added task #1: Finish the TaskBridge project README`

**Prompt:** "List my tasks"
**Result:** `#1 — Finish the TaskBridge project README (not yet completed)`

## Limitations

- Tasks are stored in a single local JSON file, not a real database -
  fine for a single user, not built for concurrency.
- No authentication - anyone with access to Claude Desktop and this
  config can manage the task list.
- No due dates, priorities, or categories - deliberately minimal to keep
  the MCP mechanics clear.

## What I Learned

The most instructive part of building TaskBridge was seeing how different
connecting an AI model to a real system is from simply calling it through
an API. I learned how tools are defined through MCP, why correct path
handling and security matter when a program interacts with the file
system, and how giving an AI access to external resources introduces new
categories of failure and risk. The most interesting realization was that
connecting an AI to a system doesn't automatically make it trustworthy -
how the tools and permissions around it are designed matters just as much
as the model itself.

## Author

Alhaz Almus - Philosophy student, METU