encarapi-mcp 1.0.0 → 1.2.0
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.
- package/README.md +97 -6
- package/package.json +6 -4
- package/src/app.js +183 -0
- package/src/brand.js +41 -0
- package/src/http.js +6 -90
- package/src/oauth.js +657 -0
- package/src/server.js +234 -162
package/src/server.js
CHANGED
|
@@ -4,7 +4,7 @@ import encarapi from "encarapi";
|
|
|
4
4
|
|
|
5
5
|
const { KoreaClient, ChinaClient } = encarapi;
|
|
6
6
|
|
|
7
|
-
export const VERSION = "1.
|
|
7
|
+
export const VERSION = "1.2.0";
|
|
8
8
|
const MAX_TEXT = 40000;
|
|
9
9
|
|
|
10
10
|
const asText = (data) => {
|
|
@@ -13,10 +13,18 @@ const asText = (data) => {
|
|
|
13
13
|
return { content: [{ type: "text", text }] };
|
|
14
14
|
};
|
|
15
15
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
16
|
+
// Plan gates (403) and rate limits (429) answer with { error, hint }: the agent gets
|
|
17
|
+
// that text as is, since it says what the plan covers and how to get more.
|
|
18
|
+
const asError = (e) => {
|
|
19
|
+
let text = String(e?.message || e);
|
|
20
|
+
if (e?.status === 403 || e?.status === 429) {
|
|
21
|
+
try {
|
|
22
|
+
const body = JSON.parse(e.body);
|
|
23
|
+
if (body?.error && body?.hint) text = `${body.error} ${body.hint}`;
|
|
24
|
+
} catch {}
|
|
25
|
+
}
|
|
26
|
+
return { isError: true, content: [{ type: "text", text }] };
|
|
27
|
+
};
|
|
20
28
|
|
|
21
29
|
const firstPhoto = (photos) => {
|
|
22
30
|
const p = Array.isArray(photos) ? photos[0] : null;
|
|
@@ -64,22 +72,49 @@ const chinaItem = (c) => ({
|
|
|
64
72
|
|
|
65
73
|
const readOnly = { readOnlyHint: true, openWorldHint: true };
|
|
66
74
|
|
|
75
|
+
const chinaSource = z
|
|
76
|
+
.enum(["dongchedi", "che168"])
|
|
77
|
+
.optional()
|
|
78
|
+
.describe("Marketplace of the id, from the search result; needed when an id exists on both");
|
|
79
|
+
|
|
80
|
+
// Every API call carries "encarapi-mcp/<version> (<transport>)" as User-Agent,
|
|
81
|
+
// so MCP usage can be told apart from other clients on the API side.
|
|
82
|
+
function withUserAgent(fetchImpl, transport) {
|
|
83
|
+
const base = fetchImpl || globalThis.fetch;
|
|
84
|
+
const ua = `encarapi-mcp/${VERSION} (${transport})`;
|
|
85
|
+
return (url, init = {}) => base(url, { ...init, headers: { ...(init.headers || {}), "User-Agent": ua } });
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const SERVER_INFO = {
|
|
89
|
+
korea: {
|
|
90
|
+
info: { name: "encarapi", title: "EnCarAPI - Korean & Chinese used car data", version: VERSION },
|
|
91
|
+
instructions:
|
|
92
|
+
"Live used car listings from South Korea (Encar, KB Chachacha, K Car) and China (Dongchedi, Che168). " +
|
|
93
|
+
"Korean prices are in KRW, Chinese prices in CNY with USD/EUR conversions. " +
|
|
94
|
+
"Use find_korean_models or korean_filter_values to get exact names before filtering. " +
|
|
95
|
+
"Requires an API key from https://encarapi.com (China: https://chinacarapi.com).",
|
|
96
|
+
},
|
|
97
|
+
china: {
|
|
98
|
+
info: { name: "chinacarapi", title: "ChinaCarAPI - Chinese & Korean used car data", version: VERSION },
|
|
99
|
+
instructions:
|
|
100
|
+
"Live used car listings from China (Dongchedi, Che168) and South Korea (Encar, KB Chachacha, K Car). " +
|
|
101
|
+
"Chinese prices are in CNY with USD/EUR conversions, Korean prices in KRW. " +
|
|
102
|
+
"Use chinese_filter_values (makes, fuels, cities) and chinese_models to get exact values before filtering " +
|
|
103
|
+
"search_chinese_cars; for Korea use find_korean_models or korean_filter_values. " +
|
|
104
|
+
"Requires an API key from https://chinacarapi.com (Korea: https://encarapi.com).",
|
|
105
|
+
},
|
|
106
|
+
};
|
|
107
|
+
|
|
67
108
|
/**
|
|
68
109
|
* Builds an MCP server for one caller. `apiKey` is an EnCarAPI key (Korean data;
|
|
69
110
|
* also Chinese data if it has the China add-on), `chinaKey` an optional separate
|
|
70
|
-
* ChinaCarAPI key.
|
|
111
|
+
* ChinaCarAPI key. `brand` ("korea" | "china") sets the server instructions and
|
|
112
|
+
* which tools are listed first.
|
|
71
113
|
*/
|
|
72
|
-
export function createServer({ apiKey, chinaKey, fetchImpl } = {}) {
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
instructions:
|
|
77
|
-
"Live used car listings from South Korea (Encar, KB Chachacha, K Car) and China (Dongchedi, Che168). " +
|
|
78
|
-
"Korean prices are in KRW, Chinese prices in CNY with USD/EUR conversions. " +
|
|
79
|
-
"Use find_korean_models or korean_filter_values to get exact names before filtering. " +
|
|
80
|
-
"Requires an API key from https://encarapi.com (China: https://chinacarapi.com).",
|
|
81
|
-
}
|
|
82
|
-
);
|
|
114
|
+
export function createServer({ apiKey, chinaKey, fetchImpl, transport = "stdio", brand = "korea" } = {}) {
|
|
115
|
+
fetchImpl = withUserAgent(fetchImpl, transport);
|
|
116
|
+
const meta = SERVER_INFO[brand] || SERVER_INFO.korea;
|
|
117
|
+
const server = new McpServer(meta.info, { instructions: meta.instructions });
|
|
83
118
|
|
|
84
119
|
const korea = apiKey ? new KoreaClient(apiKey, { fetch: fetchImpl }) : null;
|
|
85
120
|
const china = chinaKey || apiKey ? new ChinaClient(chinaKey || apiKey, { fetch: fetchImpl }) : null;
|
|
@@ -101,164 +136,201 @@ export function createServer({ apiKey, chinaKey, fetchImpl } = {}) {
|
|
|
101
136
|
|
|
102
137
|
// -- Korea -----------------------------------------------------------------
|
|
103
138
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
139
|
+
const registerKorea = () => {
|
|
140
|
+
server.registerTool(
|
|
141
|
+
"search_korean_cars",
|
|
142
|
+
{
|
|
143
|
+
title: "Search Korean used cars",
|
|
144
|
+
description:
|
|
145
|
+
"Search live used car listings in South Korea. Default source is Encar; 'kbc' = KB Chachacha, " +
|
|
146
|
+
"'kcar' = K Car, 'all' = all three deduplicated (plan-dependent). Prices are filtered in 10,000 KRW " +
|
|
147
|
+
"units (e.g. max_price 3000 = 30,000,000 KRW). Returns the total count and compact listings.",
|
|
148
|
+
inputSchema: {
|
|
149
|
+
source: z.enum(["encar", "kbc", "kcar", "all"]).optional().describe("Marketplace; default encar"),
|
|
150
|
+
manufacturer: z.string().optional().describe("Brand in English, e.g. Hyundai, Kia, Genesis, BMW. Comma = OR"),
|
|
151
|
+
model_group: z.string().optional().describe("Model line, e.g. Grandeur, Sorento, 5 Series"),
|
|
152
|
+
model: z.string().optional().describe("Specific generation"),
|
|
153
|
+
model_search: z.string().optional().describe("Free-text model search across brands, e.g. 'GV80' or 's63 coupe'"),
|
|
154
|
+
fuel: z.enum(["gasoline", "diesel", "hybrid", "electric", "lpg", "hydrogen", "other"]).optional(),
|
|
155
|
+
transmission: z.enum(["automatic", "manual", "cvt", "semi-automatic", "other"]).optional(),
|
|
156
|
+
category: z.enum(["suv", "rv", "large", "midsize", "compact", "small", "kei", "van", "light-van", "truck", "sports", "other"]).optional(),
|
|
157
|
+
min_year: z.number().int().optional(),
|
|
158
|
+
max_year: z.number().int().optional(),
|
|
159
|
+
min_price: z.number().int().optional().describe("Minimum price in 10,000 KRW"),
|
|
160
|
+
max_price: z.number().int().optional().describe("Maximum price in 10,000 KRW"),
|
|
161
|
+
max_mileage: z.number().int().optional().describe("Maximum mileage in km"),
|
|
162
|
+
frame_clean: z.boolean().optional().describe("Only cars with an accident-free chassis frame"),
|
|
163
|
+
no_damage_cost: z.boolean().optional().describe("Only cars with zero insurance-reported repair cost"),
|
|
164
|
+
has_inspection: z.boolean().optional().describe("Only cars with an official inspection report"),
|
|
165
|
+
sort: z.enum(["newest", "price_asc", "price_desc", "mileage_asc", "mileage_desc", "year_desc", "year_asc"]).optional(),
|
|
166
|
+
limit: z.number().int().min(1).max(50).optional().describe("Results per page, default 10"),
|
|
167
|
+
page: z.number().int().min(1).optional(),
|
|
168
|
+
},
|
|
169
|
+
annotations: readOnly,
|
|
170
|
+
},
|
|
171
|
+
run(async (args) => {
|
|
172
|
+
const res = await needKorea().catalog({ ...args, limit: args.limit || 10, lang: "en", count: true });
|
|
173
|
+
return { total: res.Count, page: args.page || 1, results: (res.SearchResults || []).map(koreaItem) };
|
|
174
|
+
})
|
|
175
|
+
);
|
|
176
|
+
|
|
177
|
+
server.registerTool(
|
|
178
|
+
"get_korean_car",
|
|
179
|
+
{
|
|
180
|
+
title: "Get a Korean car",
|
|
181
|
+
description: "Full details for one Korean listing: specs, options, photos, price history, seller. Id: Encar id, 'kbc:<id>' or 'kcar:<id>'.",
|
|
182
|
+
inputSchema: { id: z.string().describe("Listing id from search_korean_cars") },
|
|
183
|
+
annotations: readOnly,
|
|
132
184
|
},
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
run(async (args) => {
|
|
136
|
-
const res = await needKorea().catalog({ ...args, limit: args.limit || 10, lang: "en", count: true });
|
|
137
|
-
return { total: res.Count, page: args.page || 1, results: (res.SearchResults || []).map(koreaItem) };
|
|
138
|
-
})
|
|
139
|
-
);
|
|
185
|
+
run(({ id }) => needKorea().vehicle(id, { lang: "en" }))
|
|
186
|
+
);
|
|
140
187
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
188
|
+
server.registerTool(
|
|
189
|
+
"get_korean_inspection",
|
|
190
|
+
{
|
|
191
|
+
title: "Get a Korean inspection report",
|
|
192
|
+
description: "Official Korean inspection report (performance check) for one car: panels, frame, mechanical condition.",
|
|
193
|
+
inputSchema: { id: z.string() },
|
|
194
|
+
annotations: readOnly,
|
|
195
|
+
},
|
|
196
|
+
run(({ id }) => needKorea().inspection(id))
|
|
197
|
+
);
|
|
151
198
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
199
|
+
server.registerTool(
|
|
200
|
+
"get_korean_accident_record",
|
|
201
|
+
{
|
|
202
|
+
title: "Get a Korean accident & ownership record",
|
|
203
|
+
description: "Insurance accident history and ownership changes for one Korean car (own vs. other-party damage in KRW).",
|
|
204
|
+
inputSchema: { id: z.string() },
|
|
205
|
+
annotations: readOnly,
|
|
206
|
+
},
|
|
207
|
+
run(({ id }) => needKorea().record(id))
|
|
208
|
+
);
|
|
162
209
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
210
|
+
server.registerTool(
|
|
211
|
+
"find_korean_models",
|
|
212
|
+
{
|
|
213
|
+
title: "Find Korean model names",
|
|
214
|
+
description: "Autocomplete model names across brands (e.g. 'sorento', 'gv70'). Use the result to filter search_korean_cars.",
|
|
215
|
+
inputSchema: { search: z.string(), limit: z.number().int().min(1).max(50).optional() },
|
|
216
|
+
annotations: readOnly,
|
|
217
|
+
},
|
|
218
|
+
run(({ search, limit }) => needKorea().modelSearch(search, { limit: limit || 10 }))
|
|
219
|
+
);
|
|
173
220
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
221
|
+
server.registerTool(
|
|
222
|
+
"korean_filter_values",
|
|
223
|
+
{
|
|
224
|
+
title: "Korean filter values",
|
|
225
|
+
description: "Valid values for the Korean search filters (fuels, colors, categories, ...).",
|
|
226
|
+
inputSchema: { source: z.enum(["encar", "kbc", "kcar", "all"]).optional() },
|
|
227
|
+
annotations: readOnly,
|
|
228
|
+
},
|
|
229
|
+
run((args) => needKorea().enums(args))
|
|
230
|
+
);
|
|
184
231
|
|
|
185
|
-
|
|
186
|
-
"korean_filter_values",
|
|
187
|
-
{
|
|
188
|
-
title: "Korean filter values",
|
|
189
|
-
description: "Valid values for the Korean search filters (fuels, colors, categories, ...).",
|
|
190
|
-
inputSchema: { source: z.enum(["encar", "kbc", "kcar", "all"]).optional() },
|
|
191
|
-
annotations: readOnly,
|
|
192
|
-
},
|
|
193
|
-
run((args) => needKorea().enums(args))
|
|
194
|
-
);
|
|
232
|
+
};
|
|
195
233
|
|
|
196
234
|
// -- China -----------------------------------------------------------------
|
|
197
235
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
236
|
+
const registerChina = () => {
|
|
237
|
+
server.registerTool(
|
|
238
|
+
"search_chinese_cars",
|
|
239
|
+
{
|
|
240
|
+
title: "Search Chinese used cars",
|
|
241
|
+
description:
|
|
242
|
+
"Search live used car listings in China (Dongchedi and Che168, duplicates merged), in English. " +
|
|
243
|
+
"Prices are in CNY; results include USD and EUR conversions. " +
|
|
244
|
+
"Use chinese_filter_values and chinese_models for exact make, model, fuel and city values.",
|
|
245
|
+
inputSchema: {
|
|
246
|
+
make: z.string().optional().describe("Brand in English, e.g. BYD, Toyota, Audi"),
|
|
247
|
+
model: z.string().optional().describe("Model name or id from chinese_models"),
|
|
248
|
+
source: z.enum(["dongchedi", "che168"]).optional().describe("Marketplace; default both"),
|
|
249
|
+
duplicates: z
|
|
250
|
+
.enum(["include"])
|
|
251
|
+
.optional()
|
|
252
|
+
.describe("'include' also returns Che168 listings that duplicate a Dongchedi listing (hidden by default)"),
|
|
253
|
+
year_min: z.number().int().optional().describe("Model year from"),
|
|
254
|
+
year_max: z.number().int().optional().describe("Model year to"),
|
|
255
|
+
reg_year_min: z.number().int().optional().describe("First registration year from"),
|
|
256
|
+
reg_year_max: z.number().int().optional().describe("First registration year to"),
|
|
257
|
+
price_min: z.number().int().optional().describe("Minimum price in CNY"),
|
|
258
|
+
price_max: z.number().int().optional().describe("Maximum price in CNY"),
|
|
259
|
+
mileage_max: z.number().int().optional().describe("Maximum mileage in km"),
|
|
260
|
+
city: z.string().optional().describe("City: pass the exact 'value' of an entry in chinese_filter_values (list 'cities')"),
|
|
261
|
+
fuel: z.string().optional().describe("Fuel type in English, see chinese_filter_values (list 'fuels')"),
|
|
262
|
+
export_ready: z.boolean().optional().describe("Only cars that can be exported now"),
|
|
263
|
+
has_report: z.boolean().optional().describe("Only cars with an inspection report"),
|
|
264
|
+
sort: z.enum(["newest", "price_asc", "price_desc", "mileage_asc", "year_desc"]).optional(),
|
|
265
|
+
lang: z.enum(["en", "zh"]).optional().describe("'zh' returns the original Chinese values; default English"),
|
|
266
|
+
limit: z.number().int().min(1).max(50).optional().describe("Results per page, default 10"),
|
|
267
|
+
page: z.number().int().min(1).optional(),
|
|
268
|
+
},
|
|
269
|
+
annotations: readOnly,
|
|
221
270
|
},
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
})
|
|
228
|
-
);
|
|
271
|
+
run(async (args) => {
|
|
272
|
+
const res = await needChina().catalog({ ...args, limit: args.limit || 10 });
|
|
273
|
+
return { total: res.total, page: res.page, results: (res.results || []).map(chinaItem) };
|
|
274
|
+
})
|
|
275
|
+
);
|
|
229
276
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
277
|
+
server.registerTool(
|
|
278
|
+
"get_chinese_car",
|
|
279
|
+
{
|
|
280
|
+
title: "Get a Chinese car",
|
|
281
|
+
description: "Full record for one Chinese listing: price history, photos, seller, export status, same car on the other marketplace.",
|
|
282
|
+
inputSchema: { id: z.string().describe("Listing id from search_chinese_cars"), source: chinaSource },
|
|
283
|
+
annotations: readOnly,
|
|
284
|
+
},
|
|
285
|
+
run(({ id, source }) => needChina().vehicle(id, { source }))
|
|
286
|
+
);
|
|
240
287
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
288
|
+
server.registerTool(
|
|
289
|
+
"get_chinese_inspection",
|
|
290
|
+
{
|
|
291
|
+
title: "Get a Chinese inspection report",
|
|
292
|
+
description: "Inspection report for one Chinese car: accident, flood and fire checks, battery data for EVs.",
|
|
293
|
+
inputSchema: { id: z.string(), source: chinaSource },
|
|
294
|
+
annotations: readOnly,
|
|
295
|
+
},
|
|
296
|
+
run(({ id, source }) => needChina().inspection(id, { source }))
|
|
297
|
+
);
|
|
298
|
+
|
|
299
|
+
server.registerTool(
|
|
300
|
+
"chinese_filter_values",
|
|
301
|
+
{
|
|
302
|
+
title: "Chinese filter values",
|
|
303
|
+
description:
|
|
304
|
+
"Valid values for the Chinese search filters, with listing counts: makes, fuels, cities, sources, sorts. " +
|
|
305
|
+
"City filters need the exact 'value' of a city entry. Pass list to get one list only.",
|
|
306
|
+
inputSchema: { list: z.enum(["makes", "fuels", "cities", "sources", "sorts"]).optional() },
|
|
307
|
+
annotations: readOnly,
|
|
308
|
+
},
|
|
309
|
+
run(async ({ list }) => {
|
|
310
|
+
const res = await needChina().enums();
|
|
311
|
+
// Compact JSON: the full set is large and must not hit the text limit.
|
|
312
|
+
return JSON.stringify(list ? { [list]: res?.[list] } : res);
|
|
313
|
+
})
|
|
314
|
+
);
|
|
251
315
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
316
|
+
server.registerTool(
|
|
317
|
+
"chinese_models",
|
|
318
|
+
{
|
|
319
|
+
title: "Chinese models of a brand",
|
|
320
|
+
description: "Models of one brand in the Chinese catalog, with listing counts.",
|
|
321
|
+
inputSchema: { make: z.string().describe("Brand name in English or brand id") },
|
|
322
|
+
annotations: readOnly,
|
|
323
|
+
},
|
|
324
|
+
run(({ make }) => needChina().models(make))
|
|
325
|
+
);
|
|
326
|
+
};
|
|
262
327
|
|
|
328
|
+
if (brand === "china") {
|
|
329
|
+
registerChina();
|
|
330
|
+
registerKorea();
|
|
331
|
+
} else {
|
|
332
|
+
registerKorea();
|
|
333
|
+
registerChina();
|
|
334
|
+
}
|
|
263
335
|
return server;
|
|
264
336
|
}
|