# Business Operations MCP Server

An MCP (Model Context Protocol) server that exposes internal business
operations — task management and internal-knowledge-base search — as tools
any MCP-compatible AI agent (Claude Desktop, Claude Code, or a custom
LangGraph/CrewAI agent) can call directly.

Built to demonstrate the core skill set behind "AI agent + business
automation" roles: designing tool interfaces an LLM can reliably call,
grounding answers in real company documents instead of letting the model
guess, and wiring that up through the Model Context Protocol so it can be
plugged into any MCP client without custom integration code per client.

## Why this exists

Most "AI agent" demos are a single chatbot wrapped around an API call. This
project instead demonstrates the actual building block enterprises need:
a **reusable, typed tool server** that any agent framework can attach to —
which is exactly what MCP was designed for, and exactly what shows up in
job descriptions asking for "MCP servers, tool orchestration, and context
integrations."

## Tools Exposed

| Tool | Description |
|---|---|
| `create_task` | Create an operational task (title, description, priority, assignee) |
| `list_tasks` | List/filter tasks by status or assignee, with pagination |
| `update_task_status` | Move a task to `open` / `in_progress` / `done` / `blocked` |
| `search_knowledge_base` | Semantic search over internal docs (RAG-style) to answer policy questions grounded in real content |

## How the RAG tool works 

`search_knowledge_base` loads every `.md`/`.txt` file in `knowledge_base/`,
builds a TF-IDF index, and ranks documents by cosine similarity to the
query. This intentionally avoids requiring an API key or external vector DB
so the server runs fully offline out of the box — the retrieval layer is
swappable for a real embedding model + vector store (e.g. OpenAI embeddings
+ Chroma/Pinecone) without changing the tool's interface, which is the
same architecture pattern used in production RAG systems.

Three sample internal documents are included (`leave_policy.md`,
`expense_policy.md`, `onboarding_process.md`) so the tool is demonstrably
useful the moment you clone the repo — ask it "how many sick days do I get"
and it retrieves the right document, not a hallucinated answer.

## Tech Stack

- **Protocol:** Model Context Protocol (MCP), official Python SDK (FastMCP)
- **Validation:** Pydantic v2 (typed inputs, constraints, auto-generated schemas)
- **Storage:** SQLite (tasks) — zero external dependencies to run
- **Retrieval:** scikit-learn TF-IDF + cosine similarity (swappable for a vector DB)

## Setup & Run

```bash
# Clone the repository
git clone https://github.com/shdbfrz/Business-Operations-MCP-Server-AI-Agent-Tooling-for-Task-Management-Knowledge-Base-Retrieval.git
cd business-ops-mcp

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the server (stdio transport — for local MCP clients)
python server.py
```

## Connecting to Claude Desktop

Add to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "business_ops": {
      "command": "python",
      "args": ["/absolute/path/to/business-ops-mcp/server.py"]
    }
  }
}
```

Restart Claude Desktop, and the four tools become available to call directly
in conversation — e.g. "create a high-priority task to follow up with the
vendor" or "what's our expense reimbursement policy for amounts over 10,000?"

## Project Structure

```
business-ops-mcp/
├── server.py              # MCP server + tool definitions (FastMCP)
├── storage.py              # SQLite task storage + TF-IDF knowledge base search
├── knowledge_base/         # Sample internal documents for RAG search
│   ├── leave_policy.md
│   ├── expense_policy.md
│   └── onboarding_process.md
├── requirements.txt
└── README.md
```

## Design Notes

- **Typed, validated inputs**: every tool uses a Pydantic model with
  explicit `Field` constraints (min/max length, enums for status/priority)
  so the LLM gets clear, structured error messages instead of silent
  failures on bad input.
- **Read-only vs. mutating tools are annotated**: `list_tasks` and
  `search_knowledge_base` are marked `readOnlyHint=True`; `create_task` and
  `update_task_status` are not — this lets MCP clients reason about which
  tool calls are safe to retry or require confirmation.
- **Pagination built in** on `list_tasks` from the start, rather than
  bolted on later, since unbounded result sets are a common way agent tool
  calls blow up context windows.
- **Grounded answers over guesses**: `search_knowledge_base` returns an
  explicit empty-result signal (not a fabricated answer) when nothing
  relevant is found, so the calling agent knows to say "I don't know"
  instead of hallucinating a policy that doesn't exist.

## Possible Extensions

- Swap the TF-IDF retrieval for real embeddings + a vector DB (Chroma/Pinecone)
  for semantic search that generalizes beyond keyword overlap.
- Add a `draft_email` tool that composes a reply grounded in a task or KB result.
- Wrap the server with Streamable HTTP transport to make it a remote,
  multi-client MCP server instead of local stdio.
- Connect it to n8n or a LangGraph agent as an external tool node to build
  a full end-to-end workflow (e.g. Slack message → agent creates task →
  agent answers policy question from KB → posts back to Slack).

---

### Author

**Shadab Firoz** — [GitHub](https://github.com/shdbfrz) · [LinkedIn](https://linkedin.com/in/shadab-firoz-38031a30b)