appium-mcp 1.82.2 → 1.84.0

package/src/tools/interactions/find.ts

@@ -7,6 +7,7 @@ import {
   toolErrorMessage,
   readWebElementId,
 } from '../tool-response.js';
+import { withEvidence, evidenceContext } from '../evidence.js';
 
 export const findElementSchema = z.object({
   strategy: z
@@ -74,19 +75,52 @@ export default function findElement(server: FastMCP): void {
       }
       const { driver } = resolved;
 
+      const startedAt = Date.now();
+      const locator = { strategy: args.strategy, selector: args.selector };
+      const context = await evidenceContext(args.sessionId);
       try {
         const element = await driver.findElement(args.strategy, args.selector);
         const elementId = readWebElementId(element);
         if (!elementId) {
-          return errorResult('Element was returned without a valid element ID');
+          return withEvidence(
+            errorResult('Element was returned without a valid element ID'),
+            {
+              name: 'appium_find_element',
+              stage: 'locate',
+              startedAt,
+              locator,
+              context,
+            }
+          );
         }
-        return textResultWithPrimaryElementId(
-          elementId,
-          `Successfully found element ${args.selector} with strategy ${args.strategy}.`
+        return withEvidence(
+          textResultWithPrimaryElementId(
+            elementId,
+            `Successfully found element ${args.selector} with strategy ${args.strategy}.`
+          ),
+          {
+            name: 'appium_find_element',
+            stage: 'locate',
+            startedAt,
+            locator,
+            element: { webdriverId: elementId },
+            context,
+          }
         );
       } catch (err: unknown) {
-        const errorMessage = toolErrorMessage(err);
-        return errorResult(`Failed to find element. Error: ${errorMessage}`);
+        return withEvidence(
+          errorResult(
+            `Failed to find element. Error: ${toolErrorMessage(err)}`
+          ),
+          {
+            name: 'appium_find_element',
+            stage: 'locate',
+            startedAt,
+            locator,
+            context,
+            error: err,
+          }
+        );
       }
     },
   });

package/dist/scripts/eval-documentation-rag.d.ts

@@ -1,50 +0,0 @@
-/**
- * Answer-grounded RAG eval for the Appium documentation tool.
- *
- * Runs the documentation_query retrieval pipeline against a fixed set of
- * realistic queries and asks the only question that matters downstream:
- * "did the answer text actually land in the chunks an LLM would see?"
- *
- * What we measure:
- *
- *   1. answerSpanRecall@K
- *      For each query, the dataset declares short verbatim phrases lifted
- *      from the docs (`answerSpans`). We concatenate the top-K retrieved
- *      chunks and check what fraction of the spans appears in that text.
- *      "anyOf" semantics: a query that finds at least one span counts as a
- *      hit. Spans are 30-140 chars and chosen so any reasonable chunk
- *      containing the answer will include them, regardless of chunk
- *      boundaries -- so the metric is splitter-neutral.
- *
- *   2. hit@{1,3,5,10}
- *      Did any chunk at rank <= K carry any answerSpan? Direct measure of
- *      "does the LLM see the answer" at different context budgets.
- *
- *   3. MRR
- *      Mean reciprocal rank of the *first* chunk that carries an answerSpan.
- *      MRR-equivalent on content, not on file paths -- a chunk from the
- *      right file but wrong section is worth nothing here.
- *
- *   4. contextEfficiency
- *      For queries we hit, 1000 * spansCovered / totalChars(topK). Spans-per-
- *      kchar density. Low = lots of noise around the answer.
- *
- *   5. fileRecall@{5,10} (diagnostic only)
- *      Did the right *file* appear in top-K? Kept so we can spot the
- *      "right-file wrong-chunk" failure mode (right file present but no
- *      answerSpan landed).
- *
- * Match semantics: lowercase + collapse whitespace, then substring check.
- *
- * Usage (after `npm run build`):
- *   node dist/scripts/eval-documentation-rag.js \
- *        [--top-k=10] [--label=NAME] [--quiet] [--no-save]
- *
- *   --top-k=N    number of chunks to retrieve & evaluate (default 10)
- *   --label=N    label written into the saved run, useful for comparing
- *                index variants (e.g. --label=before, --label=after)
- *   --quiet      suppress the per-query log lines and table
- *   --no-save    don't persist results JSON to disk
- */
-export {};
-//# sourceMappingURL=eval-documentation-rag.d.ts.map

package/dist/scripts/eval-documentation-rag.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"eval-documentation-rag.d.ts","sourceRoot":"","sources":["../../src/scripts/eval-documentation-rag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG"}

package/dist/scripts/eval-documentation-rag.js

@@ -1,287 +0,0 @@
-/**
- * Answer-grounded RAG eval for the Appium documentation tool.
- *
- * Runs the documentation_query retrieval pipeline against a fixed set of
- * realistic queries and asks the only question that matters downstream:
- * "did the answer text actually land in the chunks an LLM would see?"
- *
- * What we measure:
- *
- *   1. answerSpanRecall@K
- *      For each query, the dataset declares short verbatim phrases lifted
- *      from the docs (`answerSpans`). We concatenate the top-K retrieved
- *      chunks and check what fraction of the spans appears in that text.
- *      "anyOf" semantics: a query that finds at least one span counts as a
- *      hit. Spans are 30-140 chars and chosen so any reasonable chunk
- *      containing the answer will include them, regardless of chunk
- *      boundaries -- so the metric is splitter-neutral.
- *
- *   2. hit@{1,3,5,10}
- *      Did any chunk at rank <= K carry any answerSpan? Direct measure of
- *      "does the LLM see the answer" at different context budgets.
- *
- *   3. MRR
- *      Mean reciprocal rank of the *first* chunk that carries an answerSpan.
- *      MRR-equivalent on content, not on file paths -- a chunk from the
- *      right file but wrong section is worth nothing here.
- *
- *   4. contextEfficiency
- *      For queries we hit, 1000 * spansCovered / totalChars(topK). Spans-per-
- *      kchar density. Low = lots of noise around the answer.
- *
- *   5. fileRecall@{5,10} (diagnostic only)
- *      Did the right *file* appear in top-K? Kept so we can spot the
- *      "right-file wrong-chunk" failure mode (right file present but no
- *      answerSpan landed).
- *
- * Match semantics: lowercase + collapse whitespace, then substring check.
- *
- * Usage (after `npm run build`):
- *   node dist/scripts/eval-documentation-rag.js \
- *        [--top-k=10] [--label=NAME] [--quiet] [--no-save]
- *
- *   --top-k=N    number of chunks to retrieve & evaluate (default 10)
- *   --label=N    label written into the saved run, useful for comparing
- *                index variants (e.g. --label=before, --label=after)
- *   --quiet      suppress the per-query log lines and table
- *   --no-save    don't persist results JSON to disk
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { queryVectorStore } from '../tools/documentation/simple-pdf-indexer.js';
-// -- arg parsing ----------------------------------------------------------
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const args = process.argv.slice(2);
-const flagSet = new Set(args);
-const QUIET = flagSet.has('--quiet');
-const NO_SAVE = flagSet.has('--no-save');
-function flagValue(name, dflt) {
-    const a = args.find((x) => x.startsWith(`${name}=`));
-    return a ? a.split('=').slice(1).join('=') : dflt;
-}
-const TOP_K = Number(flagValue('--top-k', '10'));
-const LABEL = flagValue('--label', 'default');
-// -- paths ----------------------------------------------------------------
-function resolveDatasetPath() {
-    const candidates = [
-        path.resolve(__dirname, 'rag-eval-dataset.json'),
-        path.resolve(__dirname, '../../src/scripts/rag-eval-dataset.json'),
-    ];
-    for (const p of candidates) {
-        if (fs.existsSync(p)) {
-            return p;
-        }
-    }
-    throw new Error(`rag-eval-dataset.json not found in: ${candidates.join(', ')}`);
-}
-function resolveResultsDir() {
-    const dir = path.resolve(__dirname, '../../src/scripts/eval-results');
-    fs.mkdirSync(dir, { recursive: true });
-    return dir;
-}
-// -- matching helpers -----------------------------------------------------
-function normalize(s) {
-    return s.toLowerCase().replace(/\s+/g, ' ').trim();
-}
-function chunkContainsSpan(chunkText, span) {
-    return normalize(chunkText).includes(normalize(span));
-}
-function endsWithExpected(retrievedRelPath, expected) {
-    return retrievedRelPath === expected || retrievedRelPath.endsWith(expected);
-}
-// -- per-query evaluation -------------------------------------------------
-function evaluateQuery(q, chunks) {
-    const hitRanks = [];
-    const spansCovered = new Set();
-    for (const chunk of chunks) {
-        let chunkHadHit = false;
-        for (const span of q.answerSpans) {
-            if (chunkContainsSpan(chunk.text, span)) {
-                spansCovered.add(span);
-                chunkHadHit = true;
-            }
-        }
-        if (chunkHadHit) {
-            hitRanks.push(chunk.rank);
-        }
-    }
-    const firstHitRank = hitRanks.length > 0 ? hitRanks[0] : null;
-    const spansMissing = q.answerSpans.filter((s) => !spansCovered.has(s));
-    return {
-        hitRanks,
-        firstHitRank,
-        spansCovered: [...spansCovered],
-        spansMissing,
-    };
-}
-// -- aggregation ----------------------------------------------------------
-function aggregate(results) {
-    if (results.length === 0) {
-        return {
-            count: 0,
-            answerSpanRecall: 0,
-            hitAnyAt1: 0,
-            hitAnyAt3: 0,
-            hitAnyAt5: 0,
-            hitAnyAt10: 0,
-            mrr: 0,
-            contextEfficiency: 0,
-            fileRecallAt5: 0,
-            fileRecallAt10: 0,
-        };
-    }
-    const n = results.length;
-    const mean = (xs) => xs.reduce((a, b) => a + b, 0) / xs.length;
-    const hitResults = results.filter((r) => r.hitAnyAt10 === 1);
-    return {
-        count: n,
-        answerSpanRecall: mean(results.map((r) => r.answerSpanRecall)),
-        hitAnyAt1: mean(results.map((r) => r.hitAnyAt1)),
-        hitAnyAt3: mean(results.map((r) => r.hitAnyAt3)),
-        hitAnyAt5: mean(results.map((r) => r.hitAnyAt5)),
-        hitAnyAt10: mean(results.map((r) => r.hitAnyAt10)),
-        mrr: mean(results.map((r) => r.reciprocalRank)),
-        contextEfficiency: hitResults.length
-            ? mean(hitResults.map((r) => r.contextEfficiency))
-            : 0,
-        fileRecallAt5: mean(results.map((r) => r.fileRecallAt5)),
-        fileRecallAt10: mean(results.map((r) => r.fileRecallAt10)),
-    };
-}
-function fmt(n, dp = 3) {
-    return n.toFixed(dp);
-}
-function printAggregate(label, m) {
-    const tag = `${label} (n=${m.count})`.padEnd(20);
-    console.log(`${tag}  spanRecall=${fmt(m.answerSpanRecall)}  hit@1=${fmt(m.hitAnyAt1)}  hit@3=${fmt(m.hitAnyAt3)}  hit@5=${fmt(m.hitAnyAt5)}  hit@10=${fmt(m.hitAnyAt10)}  MRR=${fmt(m.mrr)}  ctxEff=${fmt(m.contextEfficiency, 2)}  fileR@5=${fmt(m.fileRecallAt5)}`);
-}
-function printPerQueryTable(results) {
-    const header = 'id   | diff   | fhr | spans  | hit@5 | unique | sources';
-    const sep = '-'.repeat(110);
-    console.log(sep);
-    console.log(header);
-    console.log(sep);
-    for (const r of results) {
-        const fhr = r.firstHitRank === null ? ' - ' : String(r.firstHitRank).padStart(3, ' ');
-        const spans = `${r.spansCovered.length}/${r.answerSpans.length}`;
-        const matched = r.retrievedSources[0]
-            ? r.retrievedSources.slice(0, 2).join(', ')
-            : '(empty)';
-        console.log(`${r.id.padEnd(4)} | ${r.difficulty.padEnd(6)} | ${fhr} | ${spans.padEnd(6)} | ${String(r.hitAnyAt5).padEnd(5)} | ${String(r.uniqueFiles).padEnd(6)} | ${matched}`);
-    }
-    console.log(sep);
-}
-// -- main -----------------------------------------------------------------
-async function runEval() {
-    const datasetPath = resolveDatasetPath();
-    const dataset = JSON.parse(fs.readFileSync(datasetPath, 'utf-8'));
-    console.log(`\n=== Appium RAG eval (answer-grounded) ===`);
-    console.log(`Dataset: ${datasetPath}`);
-    console.log(`Queries: ${dataset.queries.length}   topK: ${TOP_K}   label: ${LABEL}\n`);
-    const perQuery = [];
-    for (const q of dataset.queries) {
-        const docs = await queryVectorStore(q.query, TOP_K);
-        const chunks = docs.map((d, i) => ({
-            rank: i + 1,
-            text: d.pageContent,
-            source: d.metadata?.relativePath ??
-                d.metadata?.filename,
-            charCount: d.pageContent.length,
-        }));
-        const retrievedSources = chunks
-            .map((c) => c.source)
-            .filter((s) => !!s);
-        const topKChars = chunks.reduce((a, c) => a + c.charCount, 0);
-        const uniqueFiles = new Set(retrievedSources).size;
-        const { hitRanks, firstHitRank, spansCovered, spansMissing } = evaluateQuery(q, chunks);
-        const answerSpanRecall = q.answerSpans.length === 0
-            ? 0
-            : spansCovered.length / q.answerSpans.length;
-        const hitAnyAt = (k) => hitRanks.some((r) => r <= k) ? 1 : 0;
-        const reciprocalRank = firstHitRank ? 1 / firstHitRank : 0;
-        const contextEfficiency = firstHitRank !== null && topKChars > 0
-            ? (1000 * spansCovered.length) / topKChars
-            : 0;
-        const fileMatched = (k) => {
-            const top = retrievedSources.slice(0, k);
-            return top.some((rs) => q.expectedSources.some((es) => endsWithExpected(rs, es)))
-                ? 1
-                : 0;
-        };
-        perQuery.push({
-            id: q.id,
-            query: q.query,
-            difficulty: q.difficulty,
-            category: q.category,
-            expectedSources: q.expectedSources,
-            answerSpans: q.answerSpans,
-            retrievedSources,
-            topKChunks: chunks.length,
-            topKChars,
-            uniqueFiles,
-            hitRanks,
-            firstHitRank,
-            spansCovered,
-            spansMissing,
-            answerSpanRecall,
-            hitAnyAt1: hitAnyAt(1),
-            hitAnyAt3: hitAnyAt(3),
-            hitAnyAt5: hitAnyAt(5),
-            hitAnyAt10: hitAnyAt(10),
-            reciprocalRank,
-            contextEfficiency,
-            fileRecallAt5: fileMatched(5),
-            fileRecallAt10: fileMatched(10),
-        });
-        if (!QUIET) {
-            const status = hitAnyAt(5) ? 'OK' : 'MISS';
-            console.log(`${status.padEnd(4)} ${q.id}  spans=${spansCovered.length}/${q.answerSpans.length}  fhr=${firstHitRank ?? '-'}`);
-        }
-    }
-    if (!QUIET) {
-        printPerQueryTable(perQuery);
-    }
-    const overall = aggregate(perQuery);
-    const byDifficulty = {};
-    for (const d of ['easy', 'medium', 'vague']) {
-        byDifficulty[d] = aggregate(perQuery.filter((r) => r.difficulty === d));
-    }
-    console.log('');
-    printAggregate('overall', overall);
-    for (const d of ['easy', 'medium', 'vague']) {
-        printAggregate(d, byDifficulty[d]);
-    }
-    console.log('');
-    if (!NO_SAVE) {
-        const run = {
-            timestamp: new Date().toISOString(),
-            label: LABEL,
-            datasetVersion: dataset.version,
-            topK: TOP_K,
-            overall,
-            byDifficulty,
-            perQuery,
-        };
-        const dir = resolveResultsDir();
-        const stamp = run.timestamp.replace(/[:.]/g, '-');
-        const outPath = path.join(dir, `${LABEL}-${stamp}.json`);
-        const labelLatestPath = path.join(dir, `${LABEL}-latest.json`);
-        const latestPath = path.join(dir, 'latest.json');
-        fs.writeFileSync(outPath, JSON.stringify(run, null, 2));
-        fs.writeFileSync(labelLatestPath, JSON.stringify(run, null, 2));
-        fs.writeFileSync(latestPath, JSON.stringify(run, null, 2));
-        console.log(`Saved: ${path.relative(process.cwd(), outPath)}`);
-        console.log(`       ${path.relative(process.cwd(), labelLatestPath)}`);
-        console.log(`       ${path.relative(process.cwd(), latestPath)}\n`);
-    }
-}
-try {
-    await runEval();
-}
-catch (err) {
-    console.error('Eval failed:', err);
-    process.exit(1);
-}
-//# sourceMappingURL=eval-documentation-rag.js.map

package/dist/scripts/eval-documentation-rag.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"eval-documentation-rag.js","sourceRoot":"","sources":["../../src/scripts/eval-documentation-rag.ts"],"names":[],"mappings":"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"}

package/dist/scripts/generate-embeddings-cache.d.ts

@@ -1,13 +0,0 @@
-/**
- * Generate the embeddings cache for the currently configured model.
- *
- * Idempotent: if a valid cache already exists for the current model and the
- * fingerprint matches documents.json, this exits quickly. Otherwise it
- * embeds all chunks and writes the cache.
- *
- * Intended for the maintainer release flow:
- *   npm run build && npm run generate-cache
- * to ensure the published tarball ships a warm cache for the default model.
- */
-export {};
-//# sourceMappingURL=generate-embeddings-cache.d.ts.map

package/dist/scripts/generate-embeddings-cache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate-embeddings-cache.d.ts","sourceRoot":"","sources":["../../src/scripts/generate-embeddings-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/scripts/generate-embeddings-cache.js

@@ -1,24 +0,0 @@
-/**
- * Generate the embeddings cache for the currently configured model.
- *
- * Idempotent: if a valid cache already exists for the current model and the
- * fingerprint matches documents.json, this exits quickly. Otherwise it
- * embeds all chunks and writes the cache.
- *
- * Intended for the maintainer release flow:
- *   npm run build && npm run generate-cache
- * to ensure the published tarball ships a warm cache for the default model.
- */
-import { queryVectorStore } from '../tools/documentation/simple-pdf-indexer.js';
-const start = Date.now();
-try {
-    // A single query forces the cold-start path inside queryVectorStore, which
-    // checks the cache and embeds+saves on miss. We don't care about results.
-    await queryVectorStore('warmup', 1);
-    console.log(`Embeddings cache ready (${Date.now() - start}ms)`);
-}
-catch (err) {
-    console.error('Failed to generate embeddings cache:', err);
-    process.exit(1);
-}
-//# sourceMappingURL=generate-embeddings-cache.js.map

package/dist/scripts/generate-embeddings-cache.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"generate-embeddings-cache.js","sourceRoot":"","sources":["../../src/scripts/generate-embeddings-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAEhF,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AACzB,IAAI,CAAC;IACH,2EAA2E;IAC3E,0EAA0E;IAC1E,MAAM,gBAAgB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,KAAK,CAAC,CAAC;AAClE,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,sCAAsC,EAAE,GAAG,CAAC,CAAC;IAC3D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}