@howells/fieldwork-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Howells
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# Fieldwork MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Web search, image search, page reading, value extraction, site maps, crawls, answers, research, entity discovery, decisions, document parsing, remote browsers, monitors and account usage as tools for any MCP client, across Exa, Firecrawl, Tavily, Parallel, Perplexity, Brave, SerpApi and Browserbase. It serves the tools from [`@howells/fieldwork-sdk`](https://www.npmjs.com/package/@howells/fieldwork-sdk) over stdio.
+
+```sh
+npx -y @howells/fieldwork-mcp --provider firecrawl
+```
+
+## Choosing providers
+
+Use one provider for everything it offers:
+
+```sh
+fieldwork-mcp --provider tavily
+```
+
+Or one provider per capability. A capability without a provider has no tool, and nothing falls back to another provider:
+
+```sh
+fieldwork-mcp --search brave --read firecrawl --product firecrawl --research exa \
+  --monitor firecrawl --browser browserbase --allow-monitor --allow-browser
+```
+
+Capabilities: `search`, `images`, `read`, `readMany`, `extract`, `product`, `map`, `crawl`, `answer`, `research`, `discover`, `decide`, `act`, `browser`, `parse`, `monitor`, `usage`. A provider that lacks the capability you route to it stops the server at start-up with an error.
+
+### Providers
+
+Each provider reads its key from the environment.
+
+| Provider | Key | Capabilities |
+| --- | --- | --- |
+| `exa` | `EXA_API_KEY` | `search`, `read`, `readMany`, `extract`, `answer`, `research`, `monitor` |
+| `firecrawl` | `FIRECRAWL_API_KEY` | `search`, `images`, `read`, `readMany`, `extract`, `product`, `map`, `crawl`, `research`, `act`, `browser`, `parse`, `monitor`, `usage` |
+| `tavily` | `TAVILY_API_KEY` | `search`, `images`, `read`, `readMany`, `map`, `crawl`, `answer`, `research`, `usage` |
+| `parallel` | `PARALLEL_API_KEY` | `search`, `images`, `read`, `readMany`, `extract`, `answer`, `research`, `discover`, `decide`, `monitor` |
+| `perplexity` | `PERPLEXITY_API_KEY` | `search`, `answer`, `research`, `decide` |
+| `brave` | `BRAVE_API_KEY` | `search`, `images`, `answer` |
+| `serpapi` | `SERPAPI_API_KEY` | `search`, `images`, `usage` |
+| `browserbase` | `BROWSERBASE_API_KEY`, and optionally `BROWSERBASE_PROJECT_ID` | `search`, `read`, `browser`, `usage` |
+
+## Options
+
+| Option | Effect |
+| --- | --- |
+| `--provider <name>` | One provider for every capability it offers. |
+| `--<capability> <name>` | One provider for one capability, for example `--monitor firecrawl` or `--browser browserbase`. |
+| `--allow-act` | Adds `run_browser_script`, which runs code in a remote browser. Off by default. |
+| `--allow-browser` | Adds `open_browser` and `close_browser`, which keep a remote browser open until it is closed or expires. Off by default. |
+| `--allow-monitor` | Adds `create_monitor`, `get_monitor`, `list_monitors`, `delete_monitor` and `list_monitor_events`. A monitor keeps running, and billing, until it is deleted. Off by default. |
+| `--max-characters <n>` | The long text one result may return. Default 20,000. |
+| `--help`, `--version` | Show the usage text or the version. |
+
+The three `--allow-*` options are separate on purpose. Each tool group starts remote browsers or creates a lasting, billed resource, so a client gets it only when you ask.
+
+## Client configuration
+
+Claude Code:
+
+```sh
+claude mcp add fieldwork -e FIRECRAWL_API_KEY=… -- npx -y @howells/fieldwork-mcp --provider firecrawl
+```
+
+Claude Desktop, Cursor and other clients that take a JSON file:
+
+```json
+{
+  "mcpServers": {
+    "fieldwork": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@howells/fieldwork-mcp",
+        "--search",
+        "parallel",
+        "--read",
+        "firecrawl"
+      ],
+      "env": { "PARALLEL_API_KEY": "…", "FIRECRAWL_API_KEY": "…" }
+    }
+  }
+}
+```
+
+## Tools
+
+Each tool serves one capability, or one method of `browser` or `monitor`. The last column lists the providers that offer it.
+
+| Tool | What it does | Providers |
+| --- | --- | --- |
+| `search_web` | Ranked pages for a query. | all eight |
+| `search_images` | Images for a query, with the page each appears on. | Firecrawl, Tavily, Parallel, Brave, SerpApi |
+| `read_page` | One page as Markdown. | Exa, Firecrawl, Tavily, Parallel, Browserbase |
+| `read_pages` | Several pages in one call; pages that fail come back in `failed`. | Exa, Firecrawl, Tavily, Parallel |
+| `extract_values` | The values a JSON Schema asks for, from one page. | Exa, Firecrawl, Parallel |
+| `read_product` | A product page's variants, from its structured data. | Firecrawl |
+| `map_site` | A site's URLs, without reading them. | Firecrawl, Tavily |
+| `crawl_site` | The text of many pages from one site. | Firecrawl, Tavily |
+| `answer_question` | A short answer with its sources, in one call. | Exa, Tavily, Parallel, Perplexity, Brave |
+| `research_question` | An answer with sources, from a job of many steps. | Exa, Firecrawl, Tavily, Parallel, Perplexity |
+| `find_entities` | Entities of one kind that meet every condition you list. | Parallel |
+| `make_decisions` | Yes or no, choice and score answers about a context, with probabilities. | Parallel, Perplexity |
+| `parse_document` | A PDF, DOCX, XLSX, PPTX, HTML or CSV file as Markdown. | Firecrawl |
+| `check_usage` | Credits used and remaining. | Firecrawl, Tavily, SerpApi, Browserbase |
+| `run_browser_script` | A script run in a remote browser. Only with `--allow-act`. | Firecrawl |
+| `open_browser` | A remote browser to drive over CDP. Only with `--allow-browser`. | Firecrawl, Browserbase |
+| `close_browser` | Closes a browser opened with `open_browser`. Only with `--allow-browser`. | Firecrawl, Browserbase |
+| `create_monitor` | A monitor that checks the web on a schedule. Only with `--allow-monitor`. | Exa, Firecrawl, Parallel |
+| `get_monitor`, `list_monitors`, `delete_monitor` | Read, list and delete monitors. Only with `--allow-monitor`. | Exa, Firecrawl, Parallel |
+| `list_monitor_events` | What a monitor found. Only with `--allow-monitor`. | Exa, Firecrawl, Parallel |
+
+Every tool's input schema lists only the options its provider supports, so a client is never offered an option that would be ignored. Results come back as `structuredContent`, without the provider's own response. Lists come back as an object (`list_monitors` returns `{ "monitors": [...] }`), and `delete_monitor` and `close_browser` return `{ "deleted": true, "id": … }` and `{ "closed": true, "id": … }`.
+
+Failures come back as results with `isError: true` and a JSON body: `code`, `message`, `retryable`, `retryAfter`, and `jobId` for a job that may still be running. Pass a `jobId` back as `resume` to collect the job instead of starting another.
+
+## Embedding
+
+```ts
+import { Fieldwork } from "@howells/fieldwork-sdk";
+import { firecrawl } from "@howells/fieldwork-sdk/firecrawl";
+import { createFieldworkServer } from "@howells/fieldwork-mcp";
+
+const server = createFieldworkServer(new Fieldwork({ adapter: firecrawl() }), {
+  allow: ["monitor"],
+});
+```
+
+`allow` names capabilities that are left out by default (`act`, `browser`, `monitor`) to include as well. `server` is an `McpServer` from `@modelcontextprotocol/server`; connect it to any transport.
+
+Node 22 or later.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { a as parseArgs, i as fieldworkFor, r as USAGE, t as createFieldworkServer } from "./server-BjeNI2GT.js";
+import { createRequire } from "node:module";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+// src/cli.ts
+const hasVersion = (value) => typeof value === "object" && value !== null && "version" in value && typeof value.version === "string";
+const readVersion = () => {
+	const manifest = createRequire(import.meta.url)("../package.json");
+	return hasVersion(manifest) ? manifest.version : "0.0.0";
+};
+try {
+	const config = parseArgs(process.argv.slice(2));
+	if (config.help) process.stderr.write(`${USAGE}\n`);
+	else if (config.version) process.stderr.write(`${readVersion()}\n`);
+	else await createFieldworkServer(fieldworkFor(config), {
+		allow: config.allow,
+		maxCharacters: config.maxCharacters,
+		version: readVersion()
+	}).connect(new StdioServerTransport());
+} catch (error) {
+	process.stderr.write(`fieldwork-mcp: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { AnyAdapter, Capability, Fieldwork } from "@howells/fieldwork-sdk";
+import { ToolsOptions } from "@howells/fieldwork-sdk/tools";
+import { McpServer } from "@modelcontextprotocol/server";
+interface FieldworkServerOptions extends ToolsOptions {
+  /** Reported to clients as the server's version. */
+  version?: string;
+}
+/**
+ * An MCP server with one tool per capability, or per method of a group
+ * capability, the Fieldwork instance offers. Tool errors come back as results
+ * with `isError: true` and a structured body, so a model can read the code
+ * and decide what to do next.
+ */
+export declare const createFieldworkServer: (web: Fieldwork<AnyAdapter>, options?: FieldworkServerOptions) => McpServer;
+export declare const PROVIDERS: readonly ["exa", "firecrawl", "tavily", "parallel", "perplexity", "brave", "serpapi", "browserbase"];
+type Provider = (typeof PROVIDERS)[number];
+/** API keys given directly; a provider without one reads its key from the environment. */
+type ApiKeys = Partial<Record<Provider, string>>;
+interface ServerConfig {
+  /** Capabilities left out by default that the flags ask for. */
+  allow: Capability[];
+  help: boolean;
+  maxCharacters?: number;
+  /** One provider for every capability it offers. */
+  provider?: Provider;
+  /** A provider per capability, which builds a router. */
+  routes: Partial<Record<Capability, Provider>>;
+  version: boolean;
+}
+/** Reads the command line. Configuration is flags only; the environment holds keys. */
+export declare const parseArgs: (argv: readonly string[]) => ServerConfig;
+/**
+ * Builds the Fieldwork instance the configuration names. A route to a
+ * provider that lacks the capability throws `Unsupported`.
+ */
+export declare const fieldworkFor: (config: ServerConfig, keys?: ApiKeys) => Fieldwork<AnyAdapter>;
+export type { ApiKeys, FieldworkServerOptions, Provider, ServerConfig };

package/dist/index.js

@@ -0,0 +1 @@
+export { n as PROVIDERS, t as createFieldworkServer, i as fieldworkFor, a as parseArgs } from "./server-BjeNI2GT.js";

package/dist/server-BjeNI2GT.js

@@ -0,0 +1,187 @@
+import { CAPABILITIES, Fieldwork, FieldworkError, runtimeRouter } from "@howells/fieldwork-sdk";
+import { brave } from "@howells/fieldwork-sdk/brave";
+import { browserbase } from "@howells/fieldwork-sdk/browserbase";
+import { exa } from "@howells/fieldwork-sdk/exa";
+import { firecrawl } from "@howells/fieldwork-sdk/firecrawl";
+import { parallel } from "@howells/fieldwork-sdk/parallel";
+import { perplexity } from "@howells/fieldwork-sdk/perplexity";
+import { serpapi } from "@howells/fieldwork-sdk/serpapi";
+import { tavily } from "@howells/fieldwork-sdk/tavily";
+import { toolError, toolsFor } from "@howells/fieldwork-sdk/tools";
+import { McpServer } from "@modelcontextprotocol/server";
+// src/config.ts
+const PROVIDERS = [
+	"exa",
+	"firecrawl",
+	"tavily",
+	"parallel",
+	"perplexity",
+	"brave",
+	"serpapi",
+	"browserbase"
+];
+const USAGE = `Usage: fieldwork-mcp [options]
+
+Serves Fieldwork's tools over MCP on stdin and stdout.
+
+Choose providers with one of:
+  --provider <name>            Every capability the provider offers.
+  --<capability> <name>        One provider per capability, for example
+                               --search parallel --read firecrawl
+                               --monitor firecrawl --browser browserbase.
+                               Capabilities: ${CAPABILITIES.join(", ")}.
+
+Providers: ${PROVIDERS.join(", ")}.
+Keys come from EXA_API_KEY, FIRECRAWL_API_KEY, TAVILY_API_KEY,
+PARALLEL_API_KEY, PERPLEXITY_API_KEY, BRAVE_API_KEY, SERPAPI_API_KEY and
+BROWSERBASE_API_KEY. Browserbase also reads BROWSERBASE_PROJECT_ID, which is
+optional.
+
+Tools that start remote browsers or create lasting, billed resources are off
+unless you ask for them:
+  --allow-act                  Offer run_browser_script, which runs code in a
+                               remote browser.
+  --allow-browser              Offer open_browser and close_browser, which
+                               keep a remote browser open until it is closed or
+                               expires.
+  --allow-monitor              Offer create_monitor, get_monitor,
+                               list_monitors, delete_monitor and
+                               list_monitor_events. A monitor keeps running and
+                               billing until it is deleted.
+
+Other options:
+  --max-characters <n>         Long text one result may return. Default 20000.
+  --help                       Show this text.
+  --version                    Show the version.`;
+const ALLOW_FLAGS = /* @__PURE__ */ new Map([
+	["--allow-act", "act"],
+	["--allow-browser", "browser"],
+	["--allow-monitor", "monitor"]
+]);
+const invalid = (message) => new FieldworkError("InvalidRequest", `${message}\n\n${USAGE}`);
+const providerFrom = (value, flag) => {
+	const found = PROVIDERS.find((name) => name === value);
+	if (found === void 0) throw invalid(`${flag} needs one of ${PROVIDERS.join(", ")}`);
+	return found;
+};
+/** Applies one flag to the configuration, taking its value from `args` when it has one. */
+const readFlag = (config, flag, args) => {
+	const allowed = ALLOW_FLAGS.get(flag);
+	const capability = CAPABILITIES.find((name) => `--${name}` === flag);
+	if (flag === "--help" || flag === "-h") config.help = true;
+	else if (flag === "--version") config.version = true;
+	else if (allowed !== void 0) config.allow = [.../* @__PURE__ */ new Set([...config.allow, allowed])];
+	else if (flag === "--provider") config.provider = providerFrom(args.shift(), flag);
+	else if (flag === "--max-characters") {
+		const value = Number(args.shift());
+		if (!Number.isInteger(value) || value < 1) throw invalid("--max-characters needs a whole number above 0");
+		config.maxCharacters = value;
+	} else if (capability === void 0) throw invalid(`Unknown option ${flag}`);
+	else config.routes[capability] = providerFrom(args.shift(), flag);
+};
+/** Reads the command line. Configuration is flags only; the environment holds keys. */
+const parseArgs = (argv) => {
+	const config = {
+		allow: [],
+		help: false,
+		routes: {},
+		version: false
+	};
+	const args = [...argv];
+	while (args.length > 0) readFlag(config, args.shift() ?? "", args);
+	return config;
+};
+const FACTORIES = {
+	brave: (apiKey) => brave({ apiKey }),
+	browserbase: (apiKey) => browserbase({ apiKey }),
+	exa: (apiKey) => exa({ apiKey }),
+	firecrawl: (apiKey) => firecrawl({ apiKey }),
+	parallel: (apiKey) => parallel({ apiKey }),
+	perplexity: (apiKey) => perplexity({ apiKey }),
+	serpapi: (apiKey) => serpapi({ apiKey }),
+	tavily: (apiKey) => tavily({ apiKey })
+};
+const adapterFor = (name, keys) => FACTORIES[name](keys[name]);
+/**
+* Builds the Fieldwork instance the configuration names. A route to a
+* provider that lacks the capability throws `Unsupported`.
+*/
+const fieldworkFor = (config, keys = {}) => {
+	const routed = CAPABILITIES.filter((capability) => config.routes[capability] !== void 0);
+	if (config.provider !== void 0 && routed.length > 0) throw invalid("Use --provider or per-capability options, not both");
+	if (config.provider !== void 0) return new Fieldwork({ adapter: adapterFor(config.provider, keys) });
+	if (routed.length === 0) throw invalid("Choose a provider");
+	const adapters = /* @__PURE__ */ new Map();
+	const routes = {};
+	for (const capability of routed) {
+		const name = config.routes[capability];
+		if (name !== void 0) {
+			const adapter = adapters.get(name) ?? adapterFor(name, keys);
+			adapters.set(name, adapter);
+			routes[capability] = adapter;
+		}
+	}
+	return new Fieldwork({ adapter: runtimeRouter(routes) });
+};
+// src/server.ts
+const isArguments = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Advertises a Fieldwork JSON Schema to MCP clients and passes every input
+* object through: the tool's own `execute` checks it, and its errors name the
+* field, the problem and the inputs the provider accepts.
+*/
+const schemaOf = (schema) => ({ "~standard": {
+	jsonSchema: {
+		input: () => schema,
+		output: () => schema
+	},
+	validate: (value) => isArguments(value) ? { value } : { issues: [{ message: "input must be a JSON object" }] },
+	vendor: "fieldwork",
+	version: 1
+} });
+/**
+* An MCP server with one tool per capability, or per method of a group
+* capability, the Fieldwork instance offers. Tool errors come back as results
+* with `isError: true` and a structured body, so a model can read the code
+* and decide what to do next.
+*/
+const createFieldworkServer = (web, options = {}) => {
+	const server = new McpServer({
+		name: "fieldwork",
+		title: "Fieldwork",
+		version: options.version ?? "0.0.0"
+	});
+	for (const tool of toolsFor(web, options)) server.registerTool(tool.name, {
+		_meta: {
+			"fieldwork/capability": tool.capability,
+			"fieldwork/method": tool.method,
+			"fieldwork/provider": tool.provider
+		},
+		annotations: tool.annotations,
+		description: tool.description,
+		inputSchema: schemaOf(tool.inputSchema),
+		outputSchema: schemaOf(tool.outputSchema),
+		title: tool.annotations.title
+	}, async (input, context) => {
+		try {
+			const result = await tool.execute(input, { signal: context.mcpReq.signal });
+			return {
+				content: [{
+					text: JSON.stringify(result),
+					type: "text"
+				}],
+				structuredContent: result
+			};
+		} catch (error) {
+			return {
+				content: [{
+					text: JSON.stringify(toolError(error)),
+					type: "text"
+				}],
+				isError: true
+			};
+		}
+	});
+	return server;
+};
+export { parseArgs as a, fieldworkFor as i, PROVIDERS as n, USAGE as r, createFieldworkServer as t };

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@howells/fieldwork-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "An MCP server for Fieldwork: web and image search, page reading, extraction, product data, crawling, answers, research, entity discovery, decisions, monitors, remote browsers and document parsing across Exa, Firecrawl, Tavily, Parallel, Perplexity, Brave, SerpApi and Browserbase, as tools for any MCP client.",
+  "keywords": [
+    "agents",
+    "exa",
+    "fieldwork",
+    "firecrawl",
+    "mcp",
+    "model-context-protocol",
+    "parallel",
+    "perplexity",
+    "tavily",
+    "web-search"
+  ],
+  "license": "MIT",
+  "author": "Daniel Howells",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/howells/fieldwork.git",
+    "directory": "packages/fieldwork-mcp"
+  },
+  "bin": {
+    "fieldwork-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.4.0",
+    "@howells/fieldwork-sdk": "^0.3.0"
+  },
+  "devDependencies": {
+    "@howells/lint": "^3.9.1",
+    "@howells/typescript-config": "^0.1.8",
+    "@modelcontextprotocol/client": "^2.4.0",
+    "@types/node": "^26.6.2",
+    "tsdown": "^0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "^5.0.1"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsdown",
+    "lint": "howells-check .",
+    "lint:fix": "howells-fix .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }