mcp-server-opencitations 0.1.1 → 0.1.3

package/dist/index.js

@@ -5,63 +5,140 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+// Import API client functions from lib.ts
+import { getCitation, getCitationCount, getCitations, getReferenceCount, getReferences, getVenueCitationCount, formatDoi, formatIssn, formatCitationAsText, formatCitationsAsText, } from "./lib.js";
 // -----------------------------------------------------------------------------
-// CONFIGURATION: Environment Variables + Command Line Args
+// CONFIGURATION
 // -----------------------------------------------------------------------------
-// Priority: Command line args > Environment variables
-// process.argv is an array of command-line arguments:
-// [0] = path to node
-// [1] = path to script
-// [2+] = user arguments
-//
-// Example: node dist/index.js --token=abc123
-//          process.argv[2] would be "--token=abc123"
 function getAccessToken() {
-    // Check command line args first
     const tokenArg = process.argv.find(arg => arg.startsWith('--token='));
     if (tokenArg) {
         return tokenArg.split('=')[1];
     }
-    // Fall back to environment variable
     return process.env.OPENCITATIONS_ACCESS_TOKEN;
 }
 const ACCESS_TOKEN = getAccessToken();
 if (!ACCESS_TOKEN) {
-    console.error("Warning: No access token set.");
+    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
+// -----------------------------------------------------------------------------
+// SERVER SETUP
+// -----------------------------------------------------------------------------
 const server = new McpServer({
     name: "opencitations-server",
-    version: "0.1.0",
+    version: "0.2.0",
 });
 // -----------------------------------------------------------------------------
 // TOOLS
 // -----------------------------------------------------------------------------
-server.registerTool("check_token", {
-    description: "Check if the OpenCitations API token is configured",
-    inputSchema: {},
-}, async () => {
-    // Never expose the actual token! Just confirm if it's set
-    const status = ACCESS_TOKEN
-        ? `Token is set (${ACCESS_TOKEN.length} characters)`
-        : "Token is NOT set. Set OPENCITATIONS_ACCESS_TOKEN environment variable.";
+// 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: {
+        doi: z.string().describe("DOI of the paper (e.g., '10.1108/jd-12-2013-0166')"),
+    },
+}, async (args) => {
+    const id = formatDoi(args.doi);
+    const count = await getCitationCount(id, ACCESS_TOKEN);
+    return {
+        content: [{
+                type: "text",
+                text: `Citation count for ${args.doi}: ${count}`,
+            }],
+    };
+});
+// 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: {
+        doi: z.string().describe("DOI of the paper (e.g., '10.7717/peerj-cs.421')"),
+    },
+}, async (args) => {
+    const id = formatDoi(args.doi);
+    const count = await getReferenceCount(id, ACCESS_TOKEN);
+    return {
+        content: [{
+                type: "text",
+                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 }],
+    };
+});
+// Tool: Get single citation by OCI
+server.registerTool("get_citation", {
+    description: "Get metadata for a specific citation using its Open Citation Identifier (OCI). " +
+        "An OCI is a unique identifier for a citation link between two papers. " +
+        "Example OCI: '06101801781-06180334099'.",
+    inputSchema: {
+        oci: z.string().describe("Open Citation Identifier (e.g., '06101801781-06180334099')"),
+    },
+}, async (args) => {
+    // Remove 'oci:' prefix if present
+    const oci = args.oci.replace(/^oci:/, "");
+    const citation = await getCitation(oci, ACCESS_TOKEN);
+    if (!citation) {
+        return {
+            content: [{ type: "text", text: `No citation found for OCI: ${args.oci}` }],
+        };
+    }
     return {
-        content: [{ type: "text", text: status }],
+        content: [{ type: "text", text: formatCitationAsText(citation) }],
     };
 });
-server.registerTool("hello", {
-    description: "A simple hello world tool",
+// Tool: Get venue citation count
+server.registerTool("venue_citation_count", {
+    description: "Get the total number of citations for all papers published in a journal/venue. " +
+        "Provide an ISSN like '0138-9130' or 'issn:0138-9130'.",
     inputSchema: {
-        name: z.string().optional().describe("Name to greet"),
+        issn: z.string().describe("ISSN of the journal (e.g., '0138-9130')"),
     },
 }, async (args) => {
-    const greeting = args.name
-        ? `Hello, ${args.name}!`
-        : "Hello!";
+    const id = formatIssn(args.issn);
+    const count = await getVenueCitationCount(id, ACCESS_TOKEN);
     return {
-        content: [{ type: "text", text: greeting }],
+        content: [{
+                type: "text",
+                text: `Total citations for venue ${args.issn}: ${count}`,
+            }],
     };
 });
 // -----------------------------------------------------------------------------

package/dist/lib.js

@@ -1,67 +1,167 @@
 // =============================================================================
-// lib.ts - Helper functions for OpenCitations MCP Server
+// OpenCitations API Client
 // =============================================================================
-// This file contains reusable functions that your tools can call.
-// Separating logic into lib.ts makes code easier to test and maintain.
+const BASE_URL = "https://api.opencitations.net/index/v2";
 // -----------------------------------------------------------------------------
-// ASYNC FUNCTION EXAMPLE
+// API Client
 // -----------------------------------------------------------------------------
 /**
- * Simulates fetching data (like from an API)
+ * Makes a request to the OpenCitations API
  *
- * In TypeScript:
- * - 'async' keyword makes this function return a Promise automatically
- * - Promise<string> is the return type annotation
- * - Whatever you 'return' becomes the resolved value of the Promise
+ * @param endpoint - API endpoint (e.g., "/citations/doi:10.1234/example")
+ * @param accessToken - Optional access token for authentication
+ * @returns Promise with the JSON response
  */
-export async function fetchData() {
-    // Simulate network delay (like a real API call would have)
-    delay(100);
-    return 'data from fetchData()';
+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);
 }
 /**
- * A utility function to create a delay (useful for simulating async operations)
+ * Get all citations (papers that cite the given identifier)
  *
- * @param ms - milliseconds to wait
- * @returns Promise that resolves after the delay
+ * @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 function delay(ms) {
-    // This is how you create a Promise manually:
-    // - 'resolve' is called when the operation succeeds
-    // - setTimeout calls resolve after 'ms' milliseconds
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export async function getCitations(id, accessToken) {
+    return apiRequest(`/citations/${id}`, accessToken);
 }
 /**
- * Simulates looking up a citation by DOI
- * Later, this will call the real OpenCitations API
+ * Get the count of references for a given identifier
  *
- * @param doi - The DOI to look up (e.g., "10.1234/example")
- * @returns Promise<Citation> - resolves to a Citation object
- * @throws Error if DOI is not found
+ * @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 lookupCitation(doi) {
-    // Simulate API delay
-    await delay(50);
-    // For now, return dummy data
-    // Later, this will make a real HTTP request to OpenCitations API
-    if (!doi || doi.trim() === '') {
-        throw new Error('DOI cannot be empty');
+export async function getReferenceCount(id, accessToken) {
+    const data = await apiRequest(`/reference-count/${id}`, accessToken);
+    if (data.length === 0) {
+        return 0;
     }
-    // Simulated response
-    return {
-        doi: doi,
-        title: `Sample Paper for ${doi}`,
-        authors: ['Alice Smith', 'Bob Jones'],
-        year: 2024,
-    };
+    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;
 }
 /**
- * Formats a Citation object into a readable string
+ * Get the total citation count for all papers in a venue (journal)
  *
- * @param citation - The citation to format
- * @returns Formatted citation string
+ * @param issn - ISSN of the venue (e.g., "issn:0138-9130")
+ * @param accessToken - Optional access token
+ * @returns Total citation count for the venue
  */
-export function formatCitation(citation) {
-    const authorList = citation.authors.join(', ');
-    return `${authorList} (${citation.year}). "${citation.title}". DOI: ${citation.doi}`;
+export async function getVenueCitationCount(issn, accessToken) {
+    const data = await apiRequest(`/venue-citation-count/${issn}`, accessToken);
+    if (data.length === 0) {
+        return 0;
+    }
+    return parseInt(data[0].count, 10);
+}
+// -----------------------------------------------------------------------------
+// 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 an ISSN into the API's expected format
+ */
+export function formatIssn(issn) {
+    // Add "issn:" prefix if not present
+    if (!issn.startsWith("issn:")) {
+        return `issn:${issn}`;
+    }
+    return issn;
+}
+/**
+ * Format a single Citation into a readable string
+ */
+export function formatCitationAsText(citation) {
+    const lines = [
+        `OCI: ${citation.oci}`,
+        `Citing: ${citation.citing}`,
+        `Cited: ${citation.cited}`,
+        `Date: ${citation.creation || "N/A"}`,
+        `Timespan: ${citation.timespan || "N/A"}`,
+        `Journal self-citation: ${citation.journal_sc || "no"}`,
+        `Author self-citation: ${citation.author_sc || "no"}`,
+    ];
+    return lines.join("\n");
+}
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-opencitations",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server for OpenCitations API",
   "license": "MIT",
   "author": "ahmeshaf",