@mrfentmen/doaj-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# DOAJ MCP
 
-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.
+Search the Directory of Open Access Journals for free full-text articles. Keyless — no signup, no API key, no environment variables.
+
+## Install
+
+```bash
+npx -y @mrfentmen/doaj-mcp
+```
+
+Or add it to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "doaj-mcp": { "command": "npx", "args": ["-y", "@mrfentmen/doaj-mcp"] }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search` | Search DOAJ open access articles |
+
+## Notes
+
+DOAJ lists vetted open access journals and their articles. Every result can be read for free.
+
+## Licence
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,3 @@
+export declare class DoajError extends Error {
+}
+export declare function search(query: string, limit?: number): Promise<string>;

package/dist/api.js

@@ -0,0 +1,69 @@
+/**
+ * DOAJ — Search the Directory of Open Access Journals for free full-text articles. Keyless: no signup, no API key, no environment variables.
+ *
+ * Verified live against doaj.org.
+ */
+const API = "https://doaj.org/api";
+export class DoajError extends Error {
+}
+const val = (v) => {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number")
+        return Number.isFinite(v) ? String(v) : "";
+    if (Array.isArray(v))
+        return v.length > 0 ? val(v[0]) : "";
+    if (v && typeof v === "object") {
+        const o = v;
+        if ("en" in o)
+            return val(o.en);
+        const first = Object.values(o)[0];
+        return first === undefined ? "" : val(first);
+    }
+    return "";
+};
+const at = (o, path) => path === "" ? o : path.split(".").reduce((acc, k) => (acc && typeof acc === "object" ? acc[k] : undefined), o);
+const rows = (v) => (Array.isArray(v) ? v : []);
+async function get(url, init, timeoutMs = 25000) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            ...init,
+            signal: ctrl.signal,
+            headers: { "user-agent": "doaj-mcp", accept: "application/json", ...(init?.headers ?? {}) },
+        });
+        if (!res.ok)
+            throw new DoajError(`DOAJ returned HTTP ${res.status}`);
+        return (await res.json());
+    }
+    catch (e) {
+        if (e instanceof DoajError)
+            throw e;
+        if (e.name === "AbortError")
+            throw new DoajError("DOAJ request timed out");
+        throw new DoajError(`DOAJ request failed: ${e.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function search(query, limit = 10) {
+    const q = query.trim();
+    if (q === "")
+        throw new DoajError("query must not be empty");
+    const size = Math.min(100, Math.max(1, limit));
+    const body = await get(`${API}/search/articles/${encodeURIComponent(q)}?pageSize=${size}`);
+    const items = rows(at(body, "results"));
+    if (items.length === 0)
+        return `DOAJ found nothing for "${q}".`;
+    const total = val(at(body, "total"));
+    const lines = items.map((r, i) => {
+        const title = val(at(r, "bibjson.title"));
+        const year = val(at(r, "bibjson.year"));
+        const journal = val(at(r, "bibjson.journal.title"));
+        const bits = [year, journal].filter((b) => b !== "").join(" · ");
+        return `${i + 1}. ${title}${bits === "" ? "" : ` — ${bits}`}`;
+    });
+    return [`DOAJ articles for "${q}" — ${total} total, showing ${items.length}`, "", ...lines].join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("doaj-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { search } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const fail = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const errorMessage = (e) => `Error: ${e instanceof Error ? e.message : String(e)}`;
+export function createServer() {
+    const server = new McpServer({ name: "doaj-mcp", version: "1.0.0" });
+    server.tool("search", "Search DOAJ open access articles", { query: z.string().min(1).describe("Search text"), limit: z.number().int().min(1).max(100).default(10).describe("How many results") }, async ({ query, limit }) => {
+        try {
+            return text(await search(query, limit));
+        }
+        catch (e) {
+            return fail(errorMessage(e));
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@mrfentmen/doaj-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "DOAJ: search open access journal articles with titles and years - keyless.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/doaj-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
+  },
+  "bin": {
+    "doaj-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "test": "node tests/smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "doaj",
+    "research",
+    "open-access",
+    "journals",
+    "papers",
+    "keyless"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}