token-optimeee 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- token_optimeee-0.1.0/.env.example +3 -0
- token_optimeee-0.1.0/.gitignore +21 -0
- token_optimeee-0.1.0/Dockerfile +37 -0
- token_optimeee-0.1.0/PKG-INFO +266 -0
- token_optimeee-0.1.0/README.md +230 -0
- token_optimeee-0.1.0/config.py +25 -0
- token_optimeee-0.1.0/docs/COMPONENTS.md +183 -0
- token_optimeee-0.1.0/docs/QUICKSTART.md +124 -0
- token_optimeee-0.1.0/install.sh +159 -0
- token_optimeee-0.1.0/pyproject.toml +47 -0
- token_optimeee-0.1.0/requirements.txt +31 -0
- token_optimeee-0.1.0/src/core/cache.py +79 -0
- token_optimeee-0.1.0/src/core/client.py +107 -0
- token_optimeee-0.1.0/src/core/db.py +438 -0
- token_optimeee-0.1.0/src/core/document_search.py +159 -0
- token_optimeee-0.1.0/src/core/tool_selection.py +96 -0
- token_optimeee-0.1.0/src/core/trim.py +48 -0
- token_optimeee-0.1.0/src/dash_api.py +152 -0
- token_optimeee-0.1.0/src/front.py +474 -0
- token_optimeee-0.1.0/src/mcp/server.py +805 -0
- token_optimeee-0.1.0/src/mcp/server_http.py +194 -0
- token_optimeee-0.1.0/token_optime/__init__.py +0 -0
- token_optimeee-0.1.0/token_optime/__main__.py +176 -0
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
FROM python:3.11-slim
|
|
2
|
+
|
|
3
|
+
WORKDIR /app
|
|
4
|
+
|
|
5
|
+
RUN pip install --no-cache-dir \
|
|
6
|
+
streamlit==1.61.1 \
|
|
7
|
+
streamlit-autorefresh==1.0.1 \
|
|
8
|
+
requests==2.34.2 \
|
|
9
|
+
pandas==3.0.5 \
|
|
10
|
+
plotly==6.9.0 \
|
|
11
|
+
psycopg2-binary \
|
|
12
|
+
pydantic==2.13.4 \
|
|
13
|
+
pydantic-settings==2.14.2 \
|
|
14
|
+
python-dotenv==1.2.2 \
|
|
15
|
+
fastapi==0.140.13 \
|
|
16
|
+
uvicorn==0.51.0
|
|
17
|
+
|
|
18
|
+
COPY config.py .
|
|
19
|
+
COPY src/front.py src/front.py
|
|
20
|
+
COPY src/dash_api.py src/dash_api.py
|
|
21
|
+
COPY src/core/db.py src/core/db.py
|
|
22
|
+
|
|
23
|
+
RUN mkdir -p /root/.streamlit
|
|
24
|
+
RUN echo '\n\
|
|
25
|
+
[server]\n\
|
|
26
|
+
port = 7738\n\
|
|
27
|
+
address = "0.0.0.0"\n\
|
|
28
|
+
headless = true\n\
|
|
29
|
+
\n\
|
|
30
|
+
[browser]\n\
|
|
31
|
+
gatherUsageStats = false\n\
|
|
32
|
+
' > /root/.streamlit/config.toml
|
|
33
|
+
|
|
34
|
+
EXPOSE 7737
|
|
35
|
+
EXPOSE 7738
|
|
36
|
+
|
|
37
|
+
CMD ["python", "src/dash_api.py"]
|
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: token-optimeee
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Token-optimised MCP proxy server for Claude Desktop
|
|
5
|
+
Requires-Python: >=3.10
|
|
6
|
+
Requires-Dist: chromadb>=1.5.9
|
|
7
|
+
Requires-Dist: fastapi>=0.140.13
|
|
8
|
+
Requires-Dist: fastmcp>=3.4.5
|
|
9
|
+
Requires-Dist: groq>=1.6.0
|
|
10
|
+
Requires-Dist: httpx>=0.28.1
|
|
11
|
+
Requires-Dist: huggingface-hub>=1.28.0
|
|
12
|
+
Requires-Dist: langchain-chroma>=1.1.0
|
|
13
|
+
Requires-Dist: langchain-community>=0.4.2
|
|
14
|
+
Requires-Dist: langchain-core>=1.6.0
|
|
15
|
+
Requires-Dist: langchain-huggingface>=1.2.2
|
|
16
|
+
Requires-Dist: langchain-text-splitters>=1.1.2
|
|
17
|
+
Requires-Dist: mcp>=1.29.0
|
|
18
|
+
Requires-Dist: numpy>=2.5.1
|
|
19
|
+
Requires-Dist: pandas>=3.0.5
|
|
20
|
+
Requires-Dist: plotly>=6.9.0
|
|
21
|
+
Requires-Dist: psycopg2-binary
|
|
22
|
+
Requires-Dist: pydantic-settings>=2.14.2
|
|
23
|
+
Requires-Dist: pydantic>=2.13.4
|
|
24
|
+
Requires-Dist: pymupdf4llm>=1.28.0
|
|
25
|
+
Requires-Dist: pymupdf>=1.28.0
|
|
26
|
+
Requires-Dist: python-dotenv>=1.2.2
|
|
27
|
+
Requires-Dist: requests>=2.34.2
|
|
28
|
+
Requires-Dist: scipy>=1.18.0
|
|
29
|
+
Requires-Dist: sentence-transformers>=5.6.1
|
|
30
|
+
Requires-Dist: sse-starlette>=3.4.6
|
|
31
|
+
Requires-Dist: streamlit-autorefresh>=1.0.1
|
|
32
|
+
Requires-Dist: streamlit>=1.61.1
|
|
33
|
+
Requires-Dist: tiktoken>=0.13.0
|
|
34
|
+
Requires-Dist: uvicorn>=0.51.0
|
|
35
|
+
Description-Content-Type: text/markdown
|
|
36
|
+
|
|
37
|
+
# 🦾 Token-optimeee
|
|
38
|
+
|
|
39
|
+
A middleware MCP server that sits between Claude Desktop and your downstream MCP servers — reducing token consumption through semantic caching, dynamic tool selection, and response trimming.
|
|
40
|
+
|
|
41
|
+
**LLM Backend:** Groq | **Vector Store:** ChromaDB | **Dashboard:** Streamlit
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 🎯 What Problem This Solves
|
|
46
|
+
|
|
47
|
+
Every Claude Desktop session sends the full schema of every connected MCP tool with every prompt. With 23+ tools registered, that's thousands of tokens injected per query — even when only one tool is needed.
|
|
48
|
+
|
|
49
|
+
Token-optimeee optimises at three levels:
|
|
50
|
+
|
|
51
|
+
1. **Semantic Tool Selection** — Only the most relevant tool schema is sent to Claude per query (ChromaDB similarity search)
|
|
52
|
+
2. **Semantic Caching** — Repeated or similar queries skip tool calls entirely and return cached answers (similarity ≥ 0.8)
|
|
53
|
+
3. **Response Trimming** — Verbose tool responses are trimmed to ≤200 tokens before entering the context window
|
|
54
|
+
|
|
55
|
+
**Real result from testing:** 91.8% schema token reduction per call.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## 📁 Project Structure
|
|
60
|
+
```
|
|
61
|
+
.
|
|
62
|
+
├── README.md
|
|
63
|
+
├── config.py # Settings & env loading
|
|
64
|
+
├── start.sh # One-click setup and launch
|
|
65
|
+
├── stop.sh # One-click
|
|
66
|
+
├── requirements.txt # Python dependencies
|
|
67
|
+
├── remote_servers.json # Remote MCP URLs
|
|
68
|
+
│
|
|
69
|
+
├── src/
|
|
70
|
+
│ ├── front.py # Streamlit dashboard
|
|
71
|
+
│ ├── core/
|
|
72
|
+
│ │ ├── cache.py # Semantic cache
|
|
73
|
+
│ │ ├── trim.py # Response trimmer
|
|
74
|
+
│ │ ├── tool_selection.py # Tool selection
|
|
75
|
+
│ │ ├── client.py # Groq/Claude client
|
|
76
|
+
│ │ ├── document_search.py # RAG (index + search)
|
|
77
|
+
│ │ └── db.py # SQLite audit logging
|
|
78
|
+
│ │
|
|
79
|
+
│ └── mcp/
|
|
80
|
+
│ ├── server.py # Main MCP server
|
|
81
|
+
│ └── server_http.py # FastAPI + metrics
|
|
82
|
+
│
|
|
83
|
+
└── storage/
|
|
84
|
+
├── chroma_db/ # ChromaDB persistent store
|
|
85
|
+
└── token_audit.db # SQLite audit logs
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Our Test Case
|
|
92
|
+
|
|
93
|
+
1. list files on /Users/../Desktop
|
|
94
|
+
2. list files on /Users/../Desktop
|
|
95
|
+
|
|
96
|
+
3. index /Users/../Desktop/leave_policy.pdf doc_id leave
|
|
97
|
+
4. what is the leave policy?
|
|
98
|
+
5. what is the leave policy?
|
|
99
|
+
6. read a file
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## 🏗️ System Architecture
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
Claude Desktop
|
|
108
|
+
│
|
|
109
|
+
▼
|
|
110
|
+
┌──────────────────────────────────────────────────────────┐
|
|
111
|
+
│ Token-Optimised MCP Server │
|
|
112
|
+
│ ┌─────────────────────────────────────────────────────┐ │
|
|
113
|
+
│ │ Exposed Tools │ │
|
|
114
|
+
│ │ • find_tool (orchestrator) │ │
|
|
115
|
+
│ │ • index_document / ask_document │ │
|
|
116
|
+
│ │ • search_all_documents / index_documents_folder │ │
|
|
117
|
+
│ └─────────────────────────────────────────────────────┘ │
|
|
118
|
+
│ ┌─────────────────────────────────────────────────────┐ │
|
|
119
|
+
│ │ Optimization Layer │ │
|
|
120
|
+
│ │ ┌──────────────┐ ┌──────────────────────────────┐ │ │
|
|
121
|
+
│ │ │ Semantic │ │ Tool Selection │ │ │
|
|
122
|
+
│ │ │ Cache │ │ (ChromaDB → top-k tools) │ │ │
|
|
123
|
+
│ │ │ (sim ≥ 0.8) │ │ │ │ │
|
|
124
|
+
│ │ └──────────────┘ └──────────────────────────────┘ │ │
|
|
125
|
+
│ │ ┌──────────────┐ ┌──────────────────────────────┐ │ │
|
|
126
|
+
│ │ │ Response │ │ Token Audit │ │ │
|
|
127
|
+
│ │ │ Trimmer │ │ (SQLite audit log) │ │ │
|
|
128
|
+
│ │ │ (≤500 tok) │ │ │ │ │
|
|
129
|
+
│ │ └──────────────┘ └──────────────────────────────┘ │ │
|
|
130
|
+
│ └─────────────────────────────────────────────────────┘ │
|
|
131
|
+
└────────────┬──────────────────┬──────────────────────────┘
|
|
132
|
+
│ │
|
|
133
|
+
▼ ▼
|
|
134
|
+
┌─────────────┐ ┌──────────────┐
|
|
135
|
+
│ Filesystem │ │ Memory MCP │
|
|
136
|
+
│ MCP │ │ (remote) │
|
|
137
|
+
│ (14 tools) │ │ (9 tools) │
|
|
138
|
+
└─────────────┘ └──────────────┘
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## 🚀 Setup — One Command
|
|
145
|
+
|
|
146
|
+
### Prerequisites
|
|
147
|
+
- Python 3.10+
|
|
148
|
+
- Node.js + npx
|
|
149
|
+
- Groq API key (free at [console.groq.com](https://console.groq.com))
|
|
150
|
+
- Claude Desktop (latest)
|
|
151
|
+
|
|
152
|
+
### Run
|
|
153
|
+
|
|
154
|
+
## Run
|
|
155
|
+
|
|
156
|
+
```bash
|
|
157
|
+
chmod +x token.sh
|
|
158
|
+
./token.sh start # start
|
|
159
|
+
./token.sh stop # stop
|
|
160
|
+
./token.sh restart # restart
|
|
161
|
+
./token.sh status # check if running
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
That's it. The script will:
|
|
165
|
+
- Check Python and Node are installed
|
|
166
|
+
- Create a virtual environment and install packages (first run: 4-5 mins)
|
|
167
|
+
- Create `.env` from `.env.example` and prompt you to add your Groq key
|
|
168
|
+
- Close Claude Desktop automatically
|
|
169
|
+
- Write the MCP config
|
|
170
|
+
- Start the server in the background (terminal can be closed)
|
|
171
|
+
- Open the dashboard in your browser
|
|
172
|
+
- Reopen Claude Desktop
|
|
173
|
+
|
|
174
|
+
### Stop
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
./stop.sh
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Or click the **⏹ Stop Token-optime** button in the dashboard.
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## 🔧 Ports
|
|
185
|
+
|
|
186
|
+
| Service | Port |
|
|
187
|
+
|---|---|
|
|
188
|
+
| FastAPI / MCP | 7737 |
|
|
189
|
+
| Streamlit Dashboard | 7738 |
|
|
190
|
+
|
|
191
|
+
These are intentionally non-default to avoid conflicts with other projects.
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## 💬 For Best Results — Tell Claude to Use Token-optime
|
|
196
|
+
|
|
197
|
+
Claude Desktop has its own built-in tools (memory, web search) that it may prefer by default. For consistent routing through Token-optime, start each conversation with:
|
|
198
|
+
|
|
199
|
+
> Use token:execute for every task. Never call other tools directly.
|
|
200
|
+
|
|
201
|
+
For PDF tasks specifically:
|
|
202
|
+
> First call token:list_indexed_documents, then token:ask_document.
|
|
203
|
+
|
|
204
|
+
**Why is this needed?** Claude decides which tool to call — Token-optime can't force it. The system prompt in the config nudges Claude, but an explicit instruction in the chat is the most reliable way to ensure Token-optime is used. This is an honest limitation of how Claude Desktop works, not a bug in Token-optime.
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## 📊 Dashboard
|
|
209
|
+
|
|
210
|
+
Access at `http://localhost:7738`
|
|
211
|
+
|
|
212
|
+
| Metric | What it means |
|
|
213
|
+
|---|---|
|
|
214
|
+
| **Schema Tokens Without Token-optime** | Tokens Claude would receive with all tool schemas |
|
|
215
|
+
| **Schema Tokens With Token-optime** | Tokens Claude actually received (1 selected schema) |
|
|
216
|
+
| **Total Tokens Saved** | Schema savings + response trim savings |
|
|
217
|
+
| **Cache Hit Rate** | % of queries that returned cached answers |
|
|
218
|
+
| **Real Groq Token Usage** | Exact token counts from Groq API (not estimates) |
|
|
219
|
+
| **Cost Saved** | Estimated savings based on Sonnet 4.6 pricing |
|
|
220
|
+
|
|
221
|
+
> **Note:** Cost estimates use Claude Sonnet 4.6 pricing ($3/1M tokens, ₹84/$). Actual cost depends on which model you use in Claude Desktop.
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## 🐛 Troubleshooting
|
|
228
|
+
|
|
229
|
+
**Token-optime already running error**
|
|
230
|
+
./stop.sh
|
|
231
|
+
./start.sh
|
|
232
|
+
|
|
233
|
+
**Port 7737 in use**
|
|
234
|
+
```bash
|
|
235
|
+
lsof -i :7737
|
|
236
|
+
kill <PID>
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
**Claude not using token:execute**
|
|
240
|
+
- Check Settings → Developer → MCP Servers — `token` should show green
|
|
241
|
+
- Add explicit instruction at start of conversation (see above)
|
|
242
|
+
|
|
243
|
+
**Tool not found for query**
|
|
244
|
+
- Rephrase more specifically — e.g. "list files in /Users/name/Desktop" instead of "show my stuff"
|
|
245
|
+
- Check `server_out.log` for similarity scores
|
|
246
|
+
|
|
247
|
+
**Dashboard offline**
|
|
248
|
+
```bash
|
|
249
|
+
cat server_out.log | tail -50
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## ⚠️ Known Limitations
|
|
255
|
+
|
|
256
|
+
- **Claude's built-in tools take priority** — memory and web search bypass Token-optime because Claude prefers its native tools
|
|
257
|
+
- **Cost estimates are approximate** — based on Sonnet 4.6 pricing; varies by model
|
|
258
|
+
- **Windows not supported** — Mac and Linux only
|
|
259
|
+
- **Tilde paths** — if a tool call fails with "file not found", use the full path e.g. `/Users/name/Desktop/file.pdf`
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## 📖 Docs
|
|
264
|
+
|
|
265
|
+
- `docs/COMPONENTS.md` — Detailed components guide
|
|
266
|
+
- `docs/QUICKSTART.md` — 5-minute quick start
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# 🦾 Token-optimeee
|
|
2
|
+
|
|
3
|
+
A middleware MCP server that sits between Claude Desktop and your downstream MCP servers — reducing token consumption through semantic caching, dynamic tool selection, and response trimming.
|
|
4
|
+
|
|
5
|
+
**LLM Backend:** Groq | **Vector Store:** ChromaDB | **Dashboard:** Streamlit
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 🎯 What Problem This Solves
|
|
10
|
+
|
|
11
|
+
Every Claude Desktop session sends the full schema of every connected MCP tool with every prompt. With 23+ tools registered, that's thousands of tokens injected per query — even when only one tool is needed.
|
|
12
|
+
|
|
13
|
+
Token-optimeee optimises at three levels:
|
|
14
|
+
|
|
15
|
+
1. **Semantic Tool Selection** — Only the most relevant tool schema is sent to Claude per query (ChromaDB similarity search)
|
|
16
|
+
2. **Semantic Caching** — Repeated or similar queries skip tool calls entirely and return cached answers (similarity ≥ 0.8)
|
|
17
|
+
3. **Response Trimming** — Verbose tool responses are trimmed to ≤200 tokens before entering the context window
|
|
18
|
+
|
|
19
|
+
**Real result from testing:** 91.8% schema token reduction per call.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 📁 Project Structure
|
|
24
|
+
```
|
|
25
|
+
.
|
|
26
|
+
├── README.md
|
|
27
|
+
├── config.py # Settings & env loading
|
|
28
|
+
├── start.sh # One-click setup and launch
|
|
29
|
+
├── stop.sh # One-click
|
|
30
|
+
├── requirements.txt # Python dependencies
|
|
31
|
+
├── remote_servers.json # Remote MCP URLs
|
|
32
|
+
│
|
|
33
|
+
├── src/
|
|
34
|
+
│ ├── front.py # Streamlit dashboard
|
|
35
|
+
│ ├── core/
|
|
36
|
+
│ │ ├── cache.py # Semantic cache
|
|
37
|
+
│ │ ├── trim.py # Response trimmer
|
|
38
|
+
│ │ ├── tool_selection.py # Tool selection
|
|
39
|
+
│ │ ├── client.py # Groq/Claude client
|
|
40
|
+
│ │ ├── document_search.py # RAG (index + search)
|
|
41
|
+
│ │ └── db.py # SQLite audit logging
|
|
42
|
+
│ │
|
|
43
|
+
│ └── mcp/
|
|
44
|
+
│ ├── server.py # Main MCP server
|
|
45
|
+
│ └── server_http.py # FastAPI + metrics
|
|
46
|
+
│
|
|
47
|
+
└── storage/
|
|
48
|
+
├── chroma_db/ # ChromaDB persistent store
|
|
49
|
+
└── token_audit.db # SQLite audit logs
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Our Test Case
|
|
56
|
+
|
|
57
|
+
1. list files on /Users/../Desktop
|
|
58
|
+
2. list files on /Users/../Desktop
|
|
59
|
+
|
|
60
|
+
3. index /Users/../Desktop/leave_policy.pdf doc_id leave
|
|
61
|
+
4. what is the leave policy?
|
|
62
|
+
5. what is the leave policy?
|
|
63
|
+
6. read a file
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## 🏗️ System Architecture
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
Claude Desktop
|
|
72
|
+
│
|
|
73
|
+
▼
|
|
74
|
+
┌──────────────────────────────────────────────────────────┐
|
|
75
|
+
│ Token-Optimised MCP Server │
|
|
76
|
+
│ ┌─────────────────────────────────────────────────────┐ │
|
|
77
|
+
│ │ Exposed Tools │ │
|
|
78
|
+
│ │ • find_tool (orchestrator) │ │
|
|
79
|
+
│ │ • index_document / ask_document │ │
|
|
80
|
+
│ │ • search_all_documents / index_documents_folder │ │
|
|
81
|
+
│ └─────────────────────────────────────────────────────┘ │
|
|
82
|
+
│ ┌─────────────────────────────────────────────────────┐ │
|
|
83
|
+
│ │ Optimization Layer │ │
|
|
84
|
+
│ │ ┌──────────────┐ ┌──────────────────────────────┐ │ │
|
|
85
|
+
│ │ │ Semantic │ │ Tool Selection │ │ │
|
|
86
|
+
│ │ │ Cache │ │ (ChromaDB → top-k tools) │ │ │
|
|
87
|
+
│ │ │ (sim ≥ 0.8) │ │ │ │ │
|
|
88
|
+
│ │ └──────────────┘ └──────────────────────────────┘ │ │
|
|
89
|
+
│ │ ┌──────────────┐ ┌──────────────────────────────┐ │ │
|
|
90
|
+
│ │ │ Response │ │ Token Audit │ │ │
|
|
91
|
+
│ │ │ Trimmer │ │ (SQLite audit log) │ │ │
|
|
92
|
+
│ │ │ (≤500 tok) │ │ │ │ │
|
|
93
|
+
│ │ └──────────────┘ └──────────────────────────────┘ │ │
|
|
94
|
+
│ └─────────────────────────────────────────────────────┘ │
|
|
95
|
+
└────────────┬──────────────────┬──────────────────────────┘
|
|
96
|
+
│ │
|
|
97
|
+
▼ ▼
|
|
98
|
+
┌─────────────┐ ┌──────────────┐
|
|
99
|
+
│ Filesystem │ │ Memory MCP │
|
|
100
|
+
│ MCP │ │ (remote) │
|
|
101
|
+
│ (14 tools) │ │ (9 tools) │
|
|
102
|
+
└─────────────┘ └──────────────┘
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 🚀 Setup — One Command
|
|
109
|
+
|
|
110
|
+
### Prerequisites
|
|
111
|
+
- Python 3.10+
|
|
112
|
+
- Node.js + npx
|
|
113
|
+
- Groq API key (free at [console.groq.com](https://console.groq.com))
|
|
114
|
+
- Claude Desktop (latest)
|
|
115
|
+
|
|
116
|
+
### Run
|
|
117
|
+
|
|
118
|
+
## Run
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
chmod +x token.sh
|
|
122
|
+
./token.sh start # start
|
|
123
|
+
./token.sh stop # stop
|
|
124
|
+
./token.sh restart # restart
|
|
125
|
+
./token.sh status # check if running
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
That's it. The script will:
|
|
129
|
+
- Check Python and Node are installed
|
|
130
|
+
- Create a virtual environment and install packages (first run: 4-5 mins)
|
|
131
|
+
- Create `.env` from `.env.example` and prompt you to add your Groq key
|
|
132
|
+
- Close Claude Desktop automatically
|
|
133
|
+
- Write the MCP config
|
|
134
|
+
- Start the server in the background (terminal can be closed)
|
|
135
|
+
- Open the dashboard in your browser
|
|
136
|
+
- Reopen Claude Desktop
|
|
137
|
+
|
|
138
|
+
### Stop
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
./stop.sh
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Or click the **⏹ Stop Token-optime** button in the dashboard.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## 🔧 Ports
|
|
149
|
+
|
|
150
|
+
| Service | Port |
|
|
151
|
+
|---|---|
|
|
152
|
+
| FastAPI / MCP | 7737 |
|
|
153
|
+
| Streamlit Dashboard | 7738 |
|
|
154
|
+
|
|
155
|
+
These are intentionally non-default to avoid conflicts with other projects.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 💬 For Best Results — Tell Claude to Use Token-optime
|
|
160
|
+
|
|
161
|
+
Claude Desktop has its own built-in tools (memory, web search) that it may prefer by default. For consistent routing through Token-optime, start each conversation with:
|
|
162
|
+
|
|
163
|
+
> Use token:execute for every task. Never call other tools directly.
|
|
164
|
+
|
|
165
|
+
For PDF tasks specifically:
|
|
166
|
+
> First call token:list_indexed_documents, then token:ask_document.
|
|
167
|
+
|
|
168
|
+
**Why is this needed?** Claude decides which tool to call — Token-optime can't force it. The system prompt in the config nudges Claude, but an explicit instruction in the chat is the most reliable way to ensure Token-optime is used. This is an honest limitation of how Claude Desktop works, not a bug in Token-optime.
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## 📊 Dashboard
|
|
173
|
+
|
|
174
|
+
Access at `http://localhost:7738`
|
|
175
|
+
|
|
176
|
+
| Metric | What it means |
|
|
177
|
+
|---|---|
|
|
178
|
+
| **Schema Tokens Without Token-optime** | Tokens Claude would receive with all tool schemas |
|
|
179
|
+
| **Schema Tokens With Token-optime** | Tokens Claude actually received (1 selected schema) |
|
|
180
|
+
| **Total Tokens Saved** | Schema savings + response trim savings |
|
|
181
|
+
| **Cache Hit Rate** | % of queries that returned cached answers |
|
|
182
|
+
| **Real Groq Token Usage** | Exact token counts from Groq API (not estimates) |
|
|
183
|
+
| **Cost Saved** | Estimated savings based on Sonnet 4.6 pricing |
|
|
184
|
+
|
|
185
|
+
> **Note:** Cost estimates use Claude Sonnet 4.6 pricing ($3/1M tokens, ₹84/$). Actual cost depends on which model you use in Claude Desktop.
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## 🐛 Troubleshooting
|
|
192
|
+
|
|
193
|
+
**Token-optime already running error**
|
|
194
|
+
./stop.sh
|
|
195
|
+
./start.sh
|
|
196
|
+
|
|
197
|
+
**Port 7737 in use**
|
|
198
|
+
```bash
|
|
199
|
+
lsof -i :7737
|
|
200
|
+
kill <PID>
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
**Claude not using token:execute**
|
|
204
|
+
- Check Settings → Developer → MCP Servers — `token` should show green
|
|
205
|
+
- Add explicit instruction at start of conversation (see above)
|
|
206
|
+
|
|
207
|
+
**Tool not found for query**
|
|
208
|
+
- Rephrase more specifically — e.g. "list files in /Users/name/Desktop" instead of "show my stuff"
|
|
209
|
+
- Check `server_out.log` for similarity scores
|
|
210
|
+
|
|
211
|
+
**Dashboard offline**
|
|
212
|
+
```bash
|
|
213
|
+
cat server_out.log | tail -50
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## ⚠️ Known Limitations
|
|
219
|
+
|
|
220
|
+
- **Claude's built-in tools take priority** — memory and web search bypass Token-optime because Claude prefers its native tools
|
|
221
|
+
- **Cost estimates are approximate** — based on Sonnet 4.6 pricing; varies by model
|
|
222
|
+
- **Windows not supported** — Mac and Linux only
|
|
223
|
+
- **Tilde paths** — if a tool call fails with "file not found", use the full path e.g. `/Users/name/Desktop/file.pdf`
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## 📖 Docs
|
|
228
|
+
|
|
229
|
+
- `docs/COMPONENTS.md` — Detailed components guide
|
|
230
|
+
- `docs/QUICKSTART.md` — 5-minute quick start
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
from pydantic_settings import BaseSettings, SettingsConfigDict
|
|
2
|
+
import os
|
|
3
|
+
|
|
4
|
+
ENV_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env")
|
|
5
|
+
|
|
6
|
+
class Setting(BaseSettings):
|
|
7
|
+
groq_api_key: str
|
|
8
|
+
embedder: str = "all-MiniLM-L6-v2"
|
|
9
|
+
max_response_tokens: int = 200
|
|
10
|
+
allowed_dir: str = os.path.expanduser("~")
|
|
11
|
+
tool_confidence_threshold : float =0.30
|
|
12
|
+
remote_tool_confidence_threshold : float=0.35
|
|
13
|
+
api_port : int = 7737
|
|
14
|
+
dashboard_port : int = 7738
|
|
15
|
+
groq_model: str = "groq/compound-mini"
|
|
16
|
+
database_url: str = ""
|
|
17
|
+
|
|
18
|
+
model_config = SettingsConfigDict(
|
|
19
|
+
env_file=ENV_PATH,
|
|
20
|
+
extra="ignore"
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
settings = Setting()
|
|
24
|
+
|
|
25
|
+
PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
|