README.md•2.68 kB
# 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
---