mcp-server-opencitations 0.1.0 → 0.1.1

package/dist/index.js

@@ -1,112 +1,78 @@
 #!/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";
 // -----------------------------------------------------------------------------
-// SERVER SETUP
+// CONFIGURATION: Environment Variables + Command Line Args
 // -----------------------------------------------------------------------------
-// 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.
+// 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("  Use: --token=YOUR_TOKEN");
+    console.error("  Or set OPENCITATIONS_ACCESS_TOKEN environment variable");
+}
+// Server setup
 const server = new McpServer({
-    name: "opencitations-server", // Server identifier
-    version: "0.1.0", // Semantic versioning
+    name: "opencitations-server",
+    version: "0.1.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
-    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)"),
-    },
-}, 
-// 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
+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.";
     return {
-        content: [
-            {
-                type: "text", // 'as const' is a TypeScript assertion for literal types
-                text: greeting,
-            },
-        ],
+        content: [{ type: "text", text: status }],
     };
 });
-// -----------------------------------------------------------------------------
-// ANOTHER EXAMPLE: Tool with required parameters
-// -----------------------------------------------------------------------------
-server.registerTool("echo", {
-    description: "Echoes back the message you send (useful for testing)",
+server.registerTool("hello", {
+    description: "A simple hello world tool",
     inputSchema: {
-        // No .optional() here - this parameter is required
-        message: z.string().describe("The message to echo back"),
+        name: z.string().optional().describe("Name to greet"),
     },
 }, async (args) => {
-    // TypeScript knows args.message is definitely a string (not undefined)
+    const greeting = args.name
+        ? `Hello, ${args.name}!`
+        : "Hello!";
     return {
-        content: [
-            {
-                type: "text",
-                text: `You said: "${args.message}"`,
-            },
-        ],
+        content: [{ type: "text", text: greeting }],
     };
 });
 // -----------------------------------------------------------------------------
-// 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,67 @@
+// =============================================================================
+// lib.ts - Helper functions for OpenCitations MCP Server
+// =============================================================================
+// This file contains reusable functions that your tools can call.
+// Separating logic into lib.ts makes code easier to test and maintain.
+// -----------------------------------------------------------------------------
+// ASYNC FUNCTION EXAMPLE
+// -----------------------------------------------------------------------------
+/**
+ * Simulates fetching data (like from an 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
+ */
+export async function fetchData() {
+    // Simulate network delay (like a real API call would have)
+    delay(100);
+    return 'data from fetchData()';
+}
+/**
+ * A utility function to create a delay (useful for simulating async operations)
+ *
+ * @param ms - milliseconds to wait
+ * @returns Promise that resolves after the delay
+ */
+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));
+}
+/**
+ * Simulates looking up a citation by DOI
+ * Later, this will call the real OpenCitations API
+ *
+ * @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
+ */
+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');
+    }
+    // Simulated response
+    return {
+        doi: doi,
+        title: `Sample Paper for ${doi}`,
+        authors: ['Alice Smith', 'Bob Jones'],
+        year: 2024,
+    };
+}
+/**
+ * Formats a Citation object into a readable string
+ *
+ * @param citation - The citation to format
+ * @returns Formatted citation string
+ */
+export function formatCitation(citation) {
+    const authorList = citation.authors.join(', ');
+    return `${authorList} (${citation.year}). "${citation.title}". DOI: ${citation.doi}`;
+}

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.1",
   "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"
   }
 }