@howells/fieldwork-mcp 0.0.0-stage → 0.1.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,90 @@
-# 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, page reading, value extraction, site maps, crawls, research and document parsing as tools for any MCP client, across Exa, Firecrawl, Tavily, Parallel and Perplexity. 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 parallel --read firecrawl --product firecrawl --research exa
+```
+
+Capabilities: `search`, `read`, `extract`, `product`, `map`, `crawl`, `research`, `act`, `parse`. A provider that lacks the capability you route to it stops the server at start-up with an error.
+
+Each provider reads its key from the environment: `EXA_API_KEY`, `FIRECRAWL_API_KEY`, `TAVILY_API_KEY`, `PARALLEL_API_KEY` or `PERPLEXITY_API_KEY`.
+
+| Option | Effect |
+| --- | --- |
+| `--allow-act` | Adds `run_browser_script`, which runs code in a remote browser. Off by default. |
+| `--max-characters <n>` | The long text one result may return. Default 20,000. |
+| `--perplexity-model <id>` | The model Perplexity research runs on. |
+
+## 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
+
+| Tool | What it does |
+| --- | --- |
+| `search_web` | Ranked pages for a query. |
+| `read_page` | One page as Markdown. |
+| `extract_values` | The values a JSON Schema asks for, from one page. |
+| `read_product` | A product page's variants, from its structured data. |
+| `map_site` | A site's URLs, without reading them. |
+| `crawl_site` | The text of many pages from one site. |
+| `research_question` | An answer with sources, from a job of many steps. |
+| `parse_document` | A PDF, DOCX, XLSX, PPTX, HTML or CSV file as Markdown. |
+| `run_browser_script` | A script run in a remote browser. Only with `--allow-act`. |
+
+Every tool's input schema lists only the options its provider supports. Results come back as `structuredContent`. 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() }));
+```
+
+`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,23 @@
+#!/usr/bin/env node
+import { a as createFieldworkServer, i as parseArgs, n as USAGE, r as fieldworkFor } from "./config-CVsHltSO.js";
+import { createRequire } from "node:module";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+// src/cli.ts
+const { version } = createRequire(import.meta.url)("../package.json");
+try {
+	const config = parseArgs(process.argv.slice(2));
+	if (config.help) process.stderr.write(`${USAGE}\n`);
+	else if (config.version) process.stderr.write(`${version}\n`);
+	else {
+		const web = fieldworkFor(config);
+		await createFieldworkServer(web, {
+			version,
+			maxCharacters: config.maxCharacters,
+			capabilities: config.allowAct ? Object.entries(web.capabilities).filter(([, offered]) => offered).map(([capability]) => capability) : void 0
+		}).connect(new StdioServerTransport());
+	}
+} catch (error) {
+	process.stderr.write(`fieldwork-mcp: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+}
+export {};

package/dist/config-CVsHltSO.js

@@ -0,0 +1,156 @@
+import { toolError, toolsFor } from "@howells/fieldwork-sdk/tools";
+import { McpServer } from "@modelcontextprotocol/server";
+import { CAPABILITIES, Fieldwork, FieldworkError, router } from "@howells/fieldwork-sdk";
+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 { tavily } from "@howells/fieldwork-sdk/tavily";
+// src/server.ts
+/**
+* Advertises a Fieldwork JSON Schema to MCP clients and passes every input
+* through: the tool's own `execute` checks it, and its errors name the field,
+* the problem and the inputs the provider accepts.
+*/
+function schemaOf(schema) {
+	return { "~standard": {
+		version: 1,
+		vendor: "fieldwork",
+		validate: (value) => ({ value }),
+		jsonSchema: {
+			input: () => schema,
+			output: () => schema
+		}
+	} };
+}
+/**
+* An MCP server with one tool per 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.
+*/
+function 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, {
+		title: tool.annotations.title,
+		description: tool.description,
+		inputSchema: schemaOf(tool.inputSchema),
+		outputSchema: schemaOf(tool.outputSchema),
+		annotations: tool.annotations,
+		_meta: {
+			"fieldwork/provider": tool.provider,
+			"fieldwork/capability": tool.capability
+		}
+	}, async (input, context) => {
+		try {
+			const result = await tool.execute(input, { signal: context.mcpReq.signal });
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(result)
+				}],
+				structuredContent: result
+			};
+		} catch (error) {
+			const body = toolError(error);
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: JSON.stringify(body)
+				}]
+			};
+		}
+	});
+	return server;
+}
+// src/config.ts
+const PROVIDERS = [
+	"exa",
+	"firecrawl",
+	"tavily",
+	"parallel",
+	"perplexity"
+];
+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.
+                               Capabilities: ${CAPABILITIES.join(", ")}.
+
+Providers: ${PROVIDERS.join(", ")}.
+Keys come from EXA_API_KEY, FIRECRAWL_API_KEY, TAVILY_API_KEY,
+PARALLEL_API_KEY and PERPLEXITY_API_KEY.
+
+Options:
+  --allow-act                  Offer run_browser_script, which runs code in a
+                               remote browser. Off unless given.
+  --max-characters <n>         Long text one result may return. Default 20000.
+  --perplexity-model <id>      The model Perplexity research runs on.
+  --help                       Show this text.
+  --version                    Show the version.`;
+function invalid(message) {
+	return new FieldworkError("InvalidRequest", `${message}\n\n${USAGE}`);
+}
+function provider(value, flag) {
+	const found = PROVIDERS.find((name) => name === value);
+	if (!found) throw invalid(`${flag} needs one of ${PROVIDERS.join(", ")}`);
+	return found;
+}
+/** Reads the command line. Configuration is flags only; the environment holds keys. */
+function parseArgs(argv) {
+	const config = {
+		routes: {},
+		allowAct: false,
+		help: false,
+		version: false
+	};
+	const args = [...argv];
+	while (args.length > 0) {
+		const flag = args.shift() ?? "";
+		const name = flag.replace(/^--/u, "");
+		if (flag === "--help" || flag === "-h") config.help = true;
+		else if (flag === "--version") config.version = true;
+		else if (flag === "--allow-act") config.allowAct = true;
+		else if (flag === "--provider") config.provider = provider(args.shift(), flag);
+		else if (flag === "--perplexity-model") config.perplexityModel = args.shift();
+		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 (CAPABILITIES.includes(name)) config.routes[name] = provider(args.shift(), flag);
+		else throw invalid(`Unknown option ${flag}`);
+	}
+	return config;
+}
+function adapterFor(name, config) {
+	return {
+		exa: () => exa(),
+		firecrawl: () => firecrawl(),
+		tavily: () => tavily(),
+		parallel: () => parallel(),
+		perplexity: () => perplexity({ model: config.perplexityModel })
+	}[name]();
+}
+/** Builds the Fieldwork instance the configuration names. */
+function fieldworkFor(config) {
+	const routed = Object.entries(config.routes);
+	if (config.provider && routed.length > 0) throw invalid("Use --provider or per-capability options, not both");
+	if (config.provider) return new Fieldwork({ adapter: adapterFor(config.provider, config) });
+	if (routed.length === 0) throw invalid("Choose a provider");
+	const adapters = /* @__PURE__ */ new Map();
+	const routes = Object.fromEntries(routed.map(([capability, name]) => {
+		const adapter = adapters.get(name) ?? adapterFor(name, config);
+		adapters.set(name, adapter);
+		return [capability, adapter];
+	}));
+	return new Fieldwork({ adapter: router(routes) });
+}
+export { createFieldworkServer as a, parseArgs as i, USAGE as n, fieldworkFor as r, PROVIDERS as t };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { ToolsOptions } from "@howells/fieldwork-sdk/tools";
+import { McpServer } from "@modelcontextprotocol/server";
+import { AnyAdapter, Capability, Fieldwork } from "@howells/fieldwork-sdk";
+interface FieldworkServerOptions extends ToolsOptions {
+  /** Reported to clients as the server's version. */
+  version?: string;
+}
+/**
+ * An MCP server with one tool per 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 function createFieldworkServer(web: Fieldwork<AnyAdapter>, options?: FieldworkServerOptions): McpServer;
+export declare const PROVIDERS: readonly ["exa", "firecrawl", "tavily", "parallel", "perplexity"];
+type Provider = (typeof PROVIDERS)[number];
+interface ServerConfig {
+  /** One provider for every capability it offers. */
+  provider?: Provider;
+  /** A provider per capability, which builds a router. */
+  routes: Partial<Record<Capability, Provider>>;
+  allowAct: boolean;
+  maxCharacters?: number;
+  perplexityModel?: string;
+  help: boolean;
+  version: boolean;
+}
+/** Reads the command line. Configuration is flags only; the environment holds keys. */
+export declare function parseArgs(argv: readonly string[]): ServerConfig;
+/** Builds the Fieldwork instance the configuration names. */
+export declare function fieldworkFor(config: ServerConfig): Fieldwork<AnyAdapter>;
+export type { FieldworkServerOptions, ServerConfig };

package/dist/index.js

@@ -0,0 +1 @@
+export { t as PROVIDERS, a as createFieldworkServer, r as fieldworkFor, i as parseArgs } from "./config-CVsHltSO.js";

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.1.0",
+  "description": "An MCP server for Fieldwork: web search, page reading, extraction, crawling, research and document parsing across Exa, Firecrawl, Tavily, Parallel and Perplexity, 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.2.0"
+  },
+  "devDependencies": {
+    "@howells/lint": "^3.5.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"
+  }
 }