mcp-server-opencitations 0.1.0

package/dist/index.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// =============================================================================
+// OpenCitations MCP Server - Hello World Starter
+// =============================================================================
+// 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
+// -----------------------------------------------------------------------------
+// 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
+});
+// -----------------------------------------------------------------------------
+// TOOL REGISTRATION
+// -----------------------------------------------------------------------------
+// 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
+    return {
+        content: [
+            {
+                type: "text", // 'as const' is a TypeScript assertion for literal types
+                text: greeting,
+            },
+        ],
+    };
+});
+// -----------------------------------------------------------------------------
+// ANOTHER EXAMPLE: Tool with required parameters
+// -----------------------------------------------------------------------------
+server.registerTool("echo", {
+    description: "Echoes back the message you send (useful for testing)",
+    inputSchema: {
+        // No .optional() here - this parameter is required
+        message: z.string().describe("The message to echo back"),
+    },
+}, async (args) => {
+    // TypeScript knows args.message is definitely a string (not undefined)
+    return {
+        content: [
+            {
+                type: "text",
+                text: `You said: "${args.message}"`,
+            },
+        ],
+    };
+});
+// -----------------------------------------------------------------------------
+// START THE 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
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "mcp-server-opencitations",
+  "version": "0.1.0",
+  "description": "MCP server for OpenCitations API",
+  "license": "MIT",
+  "author": "ahmeshaf",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "opencitations",
+    "citations",
+    "api"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ahmeshaf/mcp-server-opencitations"
+  },
+  "type": "module",
+  "bin": {
+    "mcp-server-opencitations": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/*.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2"
+  }
+}