AI_SYNC MCP Server
# AI_SYNC Tooling with OpenAI + MCP
This project connects GPT-4 to a backend merchant store API using the Model Context Protocol (MCP). It allows querying and updating store data under a specific merchant class.
> ⚠️ **Note**: The server is currently hardcoded to work with the `Tnc_Store` merchant ID. Only data under this class is accessible to the AI.
---
## ⚙️ Setup Instructions
### 1. Clone the Repository
```bash
git clone https://github.com/your-org/ai_sync
cd ai_sync
````
---
### 2. Create a `.env` File
Inside the project root, create a `.env` file containing your OpenAI API key:
```env
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
---
### 3. Set Up the Python Environment with `uv`
If you haven’t installed `uv`, do so with:
```bash
curl -Ls https://astral.sh/uv/install.sh | sh
```
Then set up and activate the virtual environment:
```bash
uv venv .venv
source .venv/bin/activate
```
This will automatically install dependencies based on the `uv.lock` file.
---
### 4. Start the Merchant API Server
Ensure the backend server (AI\_SYNC) is running locally on:
```
http://localhost:4001
```
Required POST endpoints:
* `/MerchantStore/findAllStores`
* `/MerchantStore/findStore`
* `/MerchantStore/addNewStore`
---
### 5. Run the Tooling System
To launch the client and tool server together:
```bash
uv run client.py server.py
```
* `server.py` provides tool definitions via MCP
* `client.py` connects to GPT-4 and routes user queries
---
## 💬 Example Queries
```
Query: Show me all the stores for this merchant
Query: I want to add a new store, CGV Cinemas - Vincom Nguyễn Chí Thanh, Hà Nội, with keywords: CGV, rạp chiếu phim, Hà Nội, Vincom, giải trí
```
> ⚠️ For multiline input, paste it as a single line. Shift+Enter will submit prematurely in most terminals.
---
## 📁 Basic Project Structure
```
ai_sync/
├── client.py # MCP + OpenAI chat client
├── server.py # Tool server using FastMCP
├── .env # OpenAI API key
├── uv.lock # Dependency lock file (used by uv)
```
---
## ✅ Available Tools
| Tool Name | Description |
| --------------- | ------------------------------------------- |
| `findAllStores` | List all stores for `Tnc_Store` |
| `findStore` | Natural language search for relevant stores |
| `addNewStore` | Add a store with full description and tags |
---
## 🔒 Notes
* Only data for `Tnc_Store` is accessible
* Requires OpenAI GPT-4 (`gpt-4o`) and a functioning backend API
* Runs entirely locally using standard input/output
---
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: addNewStore creates a new store, findAllStores retrieves all stores for a merchant, and findStore searches stores with a natural language query. There is no overlap in functionality, and the descriptions make the distinctions explicit.
The naming is inconsistent: addNewStore uses camelCase with a verb-noun pattern, findAllStores uses camelCase with a verb-noun pattern, and findStore uses camelCase but lacks a noun (it should be findStores or similar). While all are camelCase, the lack of a consistent noun in findStore and the mix of 'New' in addNewStore versus no qualifiers in others shows poor pattern adherence.
With only 3 tools, the count feels thin for a store management domain, as it lacks update and delete operations. However, it covers basic create, list, and search functions, which is borderline but workable for minimal CRUD.
The tool set is significantly incomplete for store management. It includes add, find all, and search, but misses essential operations like update_store, delete_store, and get_store_by_id. This creates gaps that could lead to agent failures when full lifecycle management is needed.