mcp-server-opencitations 0.1.0 → 0.1.2

package/dist/index.js

@@ -1,112 +1,117 @@
 #!/usr/bin/env node
 // =============================================================================
-// OpenCitations MCP Server - Hello World Starter
+// OpenCitations MCP Server
 // =============================================================================
-// This is a minimal MCP server to help you learn TypeScript and MCP concepts.
-// Comments explain TypeScript features as we go!
-// -----------------------------------------------------------------------------
-// IMPORTS
-// -----------------------------------------------------------------------------
-// In TypeScript, we import modules using ES6 syntax.
-// The "from" path can be a package name or a relative file path.
-// McpServer is the main class that handles MCP protocol communication
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-// StdioServerTransport handles communication over stdin/stdout
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-// 'z' is Zod - a TypeScript-first schema validation library
-// It lets us define the shape of data and validate it at runtime
 import { z } from "zod";
+// Import API client functions from lib.ts
+import { getCitationCount, getCitations, getReferenceCount, getReferences, formatDoi, formatCitationsAsText, } from "./lib.js";
+// -----------------------------------------------------------------------------
+// CONFIGURATION
+// -----------------------------------------------------------------------------
+function getAccessToken() {
+    const tokenArg = process.argv.find(arg => arg.startsWith('--token='));
+    if (tokenArg) {
+        return tokenArg.split('=')[1];
+    }
+    return process.env.OPENCITATIONS_ACCESS_TOKEN;
+}
+const ACCESS_TOKEN = getAccessToken();
+if (!ACCESS_TOKEN) {
+    console.error("Warning: No access token set (optional but recommended)");
+    console.error("  Use: --token=YOUR_TOKEN");
+    console.error("  Or set OPENCITATIONS_ACCESS_TOKEN environment variable");
+}
 // -----------------------------------------------------------------------------
 // SERVER SETUP
 // -----------------------------------------------------------------------------
-// Create a new MCP server instance.
-// The object passed to McpServer is called an "object literal" in TypeScript.
-// It has typed properties: 'name' and 'version' are both strings.
 const server = new McpServer({
-    name: "opencitations-server", // Server identifier
-    version: "0.1.0", // Semantic versioning
+    name: "opencitations-server",
+    version: "0.2.0",
 });
 // -----------------------------------------------------------------------------
-// TOOL REGISTRATION
+// TOOLS
 // -----------------------------------------------------------------------------
-// MCP servers expose "tools" that LLMs can call.
-// Let's register a simple "hello" tool.
-// registerTool takes 3 arguments:
-//   1. Tool name (string)
-//   2. Tool configuration (object with description, inputSchema, etc.)
-//   3. Handler function (async function that runs when tool is called)
-server.registerTool("hello", // Tool name - this is what the LLM will use to call it
-{
-    // Human-readable description - helps LLMs understand when to use this tool
-    description: "A simple hello world tool that greets the user",
-    // inputSchema defines what parameters this tool accepts
-    // We use Zod schemas here - they provide both TypeScript types AND runtime validation
+// Tool: Get citation count
+server.registerTool("citation_count", {
+    description: "Get the number of citations for a paper (how many papers cite it). " +
+        "Provide a DOI like '10.1108/jd-12-2013-0166' or 'doi:10.1108/jd-12-2013-0166'.",
     inputSchema: {
-        // z.string() means this parameter must be a string
-        // .optional() means it's not required
-        // .describe() adds documentation for the LLM
-        name: z.string().optional().describe("Name to greet (optional)"),
+        doi: z.string().describe("DOI of the paper (e.g., '10.1108/jd-12-2013-0166')"),
     },
-}, 
-// The handler function - this runs when the tool is called
-// 'async' means this function can use 'await' for asynchronous operations
-// The parameter 'args' is automatically typed based on our inputSchema!
-async (args) => {
-    // TypeScript knows 'args.name' is string | undefined because of our schema
-    const greeting = args.name
-        ? `Hello, ${args.name}! Welcome to OpenCitations MCP server.`
-        : "Hello! Welcome to OpenCitations MCP server.";
-    // Tools return a result object with a 'content' array
-    // Each content item has a 'type' (usually "text") and the actual content
+}, async (args) => {
+    const id = formatDoi(args.doi);
+    const count = await getCitationCount(id, ACCESS_TOKEN);
     return {
-        content: [
-            {
-                type: "text", // 'as const' is a TypeScript assertion for literal types
-                text: greeting,
-            },
-        ],
+        content: [{
+                type: "text",
+                text: `Citation count for ${args.doi}: ${count}`,
+            }],
     };
 });
-// -----------------------------------------------------------------------------
-// ANOTHER EXAMPLE: Tool with required parameters
-// -----------------------------------------------------------------------------
-server.registerTool("echo", {
-    description: "Echoes back the message you send (useful for testing)",
+// Tool: Get citations (papers that cite this paper)
+server.registerTool("get_citations", {
+    description: "Get all papers that cite a given paper. " +
+        "Returns a list of citing papers with their DOIs and metadata. " +
+        "Provide a DOI like '10.1108/jd-12-2013-0166'.",
+    inputSchema: {
+        doi: z.string().describe("DOI of the paper to find citations for"),
+    },
+}, async (args) => {
+    const id = formatDoi(args.doi);
+    const citations = await getCitations(id, ACCESS_TOKEN);
+    const text = citations.length > 0
+        ? `Found ${citations.length} citations for ${args.doi}:\n\n${formatCitationsAsText(citations)}`
+        : `No citations found for ${args.doi}`;
+    return {
+        content: [{ type: "text", text }],
+    };
+});
+// Tool: Get reference count
+server.registerTool("reference_count", {
+    description: "Get the number of references in a paper (how many papers it cites). " +
+        "Provide a DOI like '10.7717/peerj-cs.421'.",
     inputSchema: {
-        // No .optional() here - this parameter is required
-        message: z.string().describe("The message to echo back"),
+        doi: z.string().describe("DOI of the paper (e.g., '10.7717/peerj-cs.421')"),
     },
 }, async (args) => {
-    // TypeScript knows args.message is definitely a string (not undefined)
+    const id = formatDoi(args.doi);
+    const count = await getReferenceCount(id, ACCESS_TOKEN);
     return {
-        content: [
-            {
+        content: [{
                 type: "text",
-                text: `You said: "${args.message}"`,
-            },
-        ],
+                text: `Reference count for ${args.doi}: ${count}`,
+            }],
+    };
+});
+// Tool: Get references (papers this paper cites)
+server.registerTool("get_references", {
+    description: "Get all papers referenced by a given paper. " +
+        "Returns a list of referenced papers with their DOIs and metadata. " +
+        "Provide a DOI like '10.7717/peerj-cs.421'.",
+    inputSchema: {
+        doi: z.string().describe("DOI of the paper to find references for"),
+    },
+}, async (args) => {
+    const id = formatDoi(args.doi);
+    const references = await getReferences(id, ACCESS_TOKEN);
+    const text = references.length > 0
+        ? `Found ${references.length} references in ${args.doi}:\n\n${formatCitationsAsText(references)}`
+        : `No references found for ${args.doi}`;
+    return {
+        content: [{ type: "text", text }],
     };
 });
 // -----------------------------------------------------------------------------
-// START THE SERVER
+// START SERVER
 // -----------------------------------------------------------------------------
-// This is an async function that starts our MCP server.
-// In TypeScript, we use 'async function' for functions that return Promises.
 async function main() {
-    // Promise<void> is the return type - void means we don't return a value
-    // The function is async, so it automatically returns a Promise
-    // Create a transport layer for stdin/stdout communication
     const transport = new StdioServerTransport();
-    // Connect the server to the transport
-    // 'await' pauses execution until the Promise resolves
     await server.connect(transport);
-    // Log to stderr (not stdout, which is used for MCP protocol messages)
     console.error("OpenCitations MCP Server running on stdio");
 }
-// Run the main function and handle any errors
-// .catch() handles any rejected promises (errors)
 main().catch((error) => {
-    // 'unknown' is a safe type for caught errors in TypeScript
     console.error("Fatal error:", error);
-    process.exit(1); // Exit with error code
+    process.exit(1);
 });

package/dist/lib.js

@@ -0,0 +1,128 @@
+// =============================================================================
+// OpenCitations API Client
+// =============================================================================
+const BASE_URL = "https://api.opencitations.net/index/v2";
+// -----------------------------------------------------------------------------
+// API Client
+// -----------------------------------------------------------------------------
+/**
+ * Makes a request to the OpenCitations API
+ *
+ * @param endpoint - API endpoint (e.g., "/citations/doi:10.1234/example")
+ * @param accessToken - Optional access token for authentication
+ * @returns Promise with the JSON response
+ */
+async function apiRequest(endpoint, accessToken) {
+    const url = `${BASE_URL}${endpoint}`;
+    const headers = {
+        "Accept": "application/json",
+    };
+    // Add authorization header if token is provided
+    if (accessToken) {
+        headers["Authorization"] = accessToken;
+    }
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}
+// -----------------------------------------------------------------------------
+// Public Functions
+// -----------------------------------------------------------------------------
+/**
+ * Get the count of citations for a given identifier
+ *
+ * @param id - Identifier with prefix (e.g., "doi:10.1108/jd-12-2013-0166")
+ * @param accessToken - Optional access token
+ * @returns Number of citations
+ */
+export async function getCitationCount(id, accessToken) {
+    const data = await apiRequest(`/citation-count/${id}`, accessToken);
+    if (data.length === 0) {
+        return 0;
+    }
+    return parseInt(data[0].count, 10);
+}
+/**
+ * Get all citations (papers that cite the given identifier)
+ *
+ * @param id - Identifier with prefix (e.g., "doi:10.1108/jd-12-2013-0166")
+ * @param accessToken - Optional access token
+ * @returns Array of Citation objects
+ */
+export async function getCitations(id, accessToken) {
+    return apiRequest(`/citations/${id}`, accessToken);
+}
+/**
+ * Get the count of references for a given identifier
+ *
+ * @param id - Identifier with prefix (e.g., "doi:10.7717/peerj-cs.421")
+ * @param accessToken - Optional access token
+ * @returns Number of references
+ */
+export async function getReferenceCount(id, accessToken) {
+    const data = await apiRequest(`/reference-count/${id}`, accessToken);
+    if (data.length === 0) {
+        return 0;
+    }
+    return parseInt(data[0].count, 10);
+}
+/**
+ * Get all references (papers cited by the given identifier)
+ *
+ * @param id - Identifier with prefix (e.g., "doi:10.7717/peerj-cs.421")
+ * @param accessToken - Optional access token
+ * @returns Array of Citation objects
+ */
+export async function getReferences(id, accessToken) {
+    return apiRequest(`/references/${id}`, accessToken);
+}
+/**
+ * Get metadata for a specific citation by OCI
+ *
+ * @param oci - Open Citation Identifier (e.g., "06101801781-06180334099")
+ * @param accessToken - Optional access token
+ * @returns Citation metadata
+ */
+export async function getCitation(oci, accessToken) {
+    const data = await apiRequest(`/citation/${oci}`, accessToken);
+    return data.length > 0 ? data[0] : null;
+}
+// -----------------------------------------------------------------------------
+// Utility Functions
+// -----------------------------------------------------------------------------
+/**
+ * Format a DOI into the API's expected format
+ * Handles both raw DOIs and prefixed DOIs
+ */
+export function formatDoi(doi) {
+    // Remove URL prefix if present
+    doi = doi.replace(/^https?:\/\/doi\.org\//, "");
+    // Add "doi:" prefix if not present
+    if (!doi.startsWith("doi:")) {
+        return `doi:${doi}`;
+    }
+    return doi;
+}
+/**
+ * Format citations into a readable string
+ */
+export function formatCitationsAsText(citations) {
+    if (citations.length === 0) {
+        return "No citations found.";
+    }
+    return citations.map((c, i) => {
+        const lines = [
+            `[${i + 1}] OCI: ${c.oci}`,
+            `    Citing: ${c.citing}`,
+            `    Cited: ${c.cited}`,
+            `    Date: ${c.creation || "N/A"}`,
+        ];
+        if (c.journal_sc === "yes")
+            lines.push("    (Journal self-citation)");
+        if (c.author_sc === "yes")
+            lines.push("    (Author self-citation)");
+        return lines.join("\n");
+    }).join("\n\n");
+}

package/dist/vitest.config.js

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'node',
+        include: ['**/__tests__/**/*.test.ts'],
+        coverage: {
+            provider: 'v8',
+            include: ['**/*.ts'],
+            exclude: ['**/__tests__/**', '**/dist/**', 'vitest.config.ts'],
+        },
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-opencitations",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for OpenCitations API",
   "license": "MIT",
   "author": "ahmeshaf",
@@ -13,7 +13,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/ahmeshaf/mcp-server-opencitations"
+    "url": "git+https://github.com/ahmeshaf/mcp-server-opencitations.git"
   },
   "type": "module",
   "bin": {
@@ -25,7 +25,10 @@
   "scripts": {
     "build": "tsc && shx chmod +x dist/*.js",
     "prepare": "npm run build",
-    "watch": "tsc --watch"
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.0",
@@ -33,7 +36,9 @@
   },
   "devDependencies": {
     "@types/node": "^22",
+    "@vitest/coverage-v8": "^2.1.8",
     "shx": "^0.3.4",
-    "typescript": "^5.8.2"
+    "typescript": "^5.8.2",
+    "vitest": "^2.1.8"
   }
 }