feat: Add typescript examples using openfigi-sdk and openfigi-mcp

typescript/openfigi-mcp/.gitignore

@@ -0,0 +1 @@
+node_modules/

typescript/openfigi-mcp/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:22-alpine
+
+WORKDIR /app
+
+COPY package.json ./
+RUN npm install
+
+CMD ["npx", "openfigi-mcp"]

typescript/openfigi-mcp/README.md

@@ -0,0 +1,81 @@
+# OpenFIGI MCP Server Example
+
+This example demonstrates how to use the [openfigi-mcp](https://www.npmjs.com/package/openfigi-mcp) package - a Model Context Protocol (MCP) server for the OpenFIGI API.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) allows AI assistants to interact with external tools and data sources. The `openfigi-mcp` server enables AI assistants like Claude to map financial identifiers to FIGIs directly.
+
+## Instructions
+
+Prerequisites: `node` (v18+) must be installed.
+
+```bash
+# Install dependencies
+npm install
+
+# Optional: Export your API key for higher rate limits
+export OPENFIGI_API_KEY=<YOUR_KEY_HERE>
+
+# Run the MCP server
+npm start
+```
+
+## Configuration with Claude Desktop
+
+Add the following to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "openfigi": {
+      "command": "npx",
+      "args": ["openfigi-mcp"],
+      "env": {
+        "OPENFIGI_API_KEY": "<YOUR_KEY_HERE>"
+      }
+    }
+  }
+}
+```
+
+## Configuration with Claude Code
+
+Add the following to your Claude Code MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "openfigi": {
+      "command": "npx",
+      "args": ["openfigi-mcp"],
+      "env": {
+        "OPENFIGI_API_KEY": "<YOUR_KEY_HERE>"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+Once configured, the MCP server provides tools to:
+- Search for financial instruments by various identifiers (ISIN, CUSIP, SEDOL, Ticker)
+- Map identifiers to FIGIs
+- Validate financial identifiers
+
+## Docker Instructions
+
+Prerequisites: `Docker` must be installed.
+
+```bash
+docker build --tag 'openfigi-mcp' .
+
+docker run --rm -it 'openfigi-mcp'
+
+# OR: If you have acquired an API Key
+docker run --rm -it -e OPENFIGI_API_KEY=<YOUR_KEY_HERE> 'openfigi-mcp'
+```

typescript/openfigi-mcp/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "openfigi-mcp-example",
+  "version": "1.0.0",
+  "description": "OpenFIGI MCP Server example",
+  "type": "module",
+  "scripts": {
+    "start": "npx openfigi-mcp"
+  },
+  "dependencies": {
+    "openfigi-mcp": "^0.4.1"
+  }
+}

typescript/openfigi-sdk/.gitignore

@@ -0,0 +1 @@
+node_modules/

typescript/openfigi-sdk/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:22-alpine
+
+WORKDIR /app
+
+COPY package.json ./
+RUN npm install
+
+COPY example.ts ./
+
+CMD ["npx", "tsx", "example.ts"]

typescript/openfigi-sdk/README.md

@@ -0,0 +1,41 @@
+# OpenFIGI SDK TypeScript Example
+
+This example demonstrates how to use the [openfigi-sdk](https://github.com/viktorlarsson/openfigi/tree/main/packages/openfigi-sdk) package to interact with the OpenFIGI API.
+
+## Features
+
+The SDK provides:
+- Type-safe API calls with TypeScript support
+- Zod schema validation
+- Helper functions for common operations (searchByISIN, searchByTicker, etc.)
+- Identifier validation (isValidISIN, isValidCUSIP)
+- Batch mapping operations
+- Built-in retry logic with exponential backoff
+
+## Instructions
+
+Prerequisites: `node` (v18+) must be installed.
+
+```bash
+# Install dependencies
+npm install
+
+# Optional: Export your API key for higher rate limits
+export OPENFIGI_API_KEY=<YOUR_KEY_HERE>
+
+# Run the example
+npm start
+```
+
+## Docker Instructions
+
+Prerequisites: `Docker` must be installed.
+
+```bash
+docker build --tag 'openfigi-sdk-example' .
+
+docker run --rm -it 'openfigi-sdk-example'
+
+# OR: If you have acquired an API Key
+docker run --rm -it -e OPENFIGI_API_KEY=<YOUR_KEY_HERE> 'openfigi-sdk-example'
+```

typescript/openfigi-sdk/example.ts

@@ -0,0 +1,93 @@
+/*
+Copyright 2017 Bloomberg Finance L.P.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+/**
+ * See https://www.openfigi.com/api for more information on the OpenFIGI API.
+ *
+ * This example demonstrates usage of the openfigi-sdk package.
+ * For more information: https://github.com/viktorlarsson/openfigi/tree/main/packages/openfigi-sdk
+ */
+
+import {
+  createClient,
+  searchByISIN,
+  searchByTicker,
+  mapping,
+  isValidISIN,
+  isValidCUSIP,
+} from "openfigi-sdk";
+
+async function main() {
+  const apiKey = process.env.OPENFIGI_API_KEY;
+
+  // Example 1: Validate identifiers before making API calls
+  console.log("=== Identifier Validation ===");
+  const testISIN = "US0378331005"; // Apple Inc.
+  const testCUSIP = "037833100";
+  console.log(`ISIN ${testISIN} is valid:`, isValidISIN(testISIN));
+  console.log(`CUSIP ${testCUSIP} is valid:`, isValidCUSIP(testCUSIP));
+
+  // Example 2: Search by ISIN (without API key - uses default client)
+  console.log("\n=== Search by ISIN ===");
+  try {
+    const isinResult = await searchByISIN(testISIN);
+    console.log("ISIN search result:", JSON.stringify(isinResult, null, 2));
+  } catch (error) {
+    console.error("ISIN search error:", error);
+  }
+
+  // Example 3: Search by Ticker with exchange code
+  console.log("\n=== Search by Ticker ===");
+  try {
+    const tickerResult = await searchByTicker("AAPL", "US");
+    console.log("Ticker search result:", JSON.stringify(tickerResult, null, 2));
+  } catch (error) {
+    console.error("Ticker search error:", error);
+  }
+
+  // Example 4: Batch mapping request
+  console.log("\n=== Batch Mapping ===");
+  try {
+    const mappingResults = await mapping([
+      { idType: "ID_ISIN", idValue: "US0378331005" },
+      { idType: "ID_CUSIP", idValue: "037833100" },
+      { idType: "ID_BB_GLOBAL", idValue: "BBG000BLNNH6" },
+    ]);
+    console.log("Mapping results:", JSON.stringify(mappingResults, null, 2));
+  } catch (error) {
+    console.error("Mapping error:", error);
+  }
+
+  // Example 5: Using a configured client with API key
+  if (apiKey) {
+    console.log("\n=== Using Configured Client with API Key ===");
+    const client = createClient({ apiKey });
+
+    try {
+      const result = await client.searchByISIN("US5949181045"); // Microsoft
+      console.log(
+        "Client search result:",
+        JSON.stringify(result, null, 2)
+      );
+    } catch (error) {
+      console.error("Client search error:", error);
+    }
+  } else {
+    console.log("\n(Set OPENFIGI_API_KEY env var to test authenticated client)");
+  }
+}
+
+main().catch(console.error);

typescript/openfigi-sdk/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "openfigi-sdk-example",
+  "version": "1.0.0",
+  "description": "OpenFIGI SDK TypeScript example",
+  "type": "module",
+  "scripts": {
+    "start": "npx tsx example.ts"
+  },
+  "dependencies": {
+    "openfigi-sdk": "^1.3.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0"
+  }
+}