get_balance

Instructions

Implementation Reference

• tests/fixtures/manifest.ts:27-27 (registration)

  The tool 'get_balance' is registered in the test manifest fixture via the mcp_tool field on line 27, linking the endpoint slug 'get-balance' to the MCP tool name 'get_balance'.

  mcp_tool: 'get_balance',

• src/manifest.ts:1-127 (schema)

  The manifest.ts file loads the API manifest (which includes the 'get_balance' endpoint definition) from a remote URL, cache, or fallback. This provides the configuration data (path, method, input_schema, etc.) for the get_balance tool.

  import { promises as fs, readFileSync } from 'node:fs'
  import os from 'node:os'
  import path from 'node:path'
  import type { ApiManifest, ManifestLoadResult, ManifestSource } from './types.js'
  
  const DEFAULT_MANIFEST_URL = 'https://www.iletimerkezi.com/api/manifest.json'
  const FETCH_TIMEOUT_MS = 5_000
  const CACHE_TTL_MS = 24 * 60 * 60 * 1_000
  
  export interface LoadOptions {
    manifestUrl?: string
    cacheDir?: string
    cacheFile?: string
    fetchImpl?: typeof fetch
    now?: () => number
    /**
     * Override the fallback search path list. Pass `[]` to disable the fallback
     * lookup entirely (useful in tests). When omitted, the production candidate
     * list is used.
     */
    fallbackPaths?: string[]
  }
  
  export function getManifestUrl(env: NodeJS.ProcessEnv = process.env): string {
    return (env.ILETIMERKEZI_MANIFEST_URL || DEFAULT_MANIFEST_URL).replace(/\/$/, '')
  }
  
  export function getCachePath(env: NodeJS.ProcessEnv = process.env): { dir: string; file: string } {
    const root = env.ILETIMERKEZI_MCP_CACHE_DIR || path.join(os.homedir(), '.cache', 'iletimerkezi-mcp')
    return { dir: root, file: path.join(root, 'manifest.json') }
  }
  
  interface CacheEnvelope {
    fetched_at: string
    manifest: ApiManifest
  }
  
  async function readCache(file: string, now: number): Promise<CacheEnvelope | null> {
    try {
      const raw = await fs.readFile(file, 'utf8')
      const parsed = JSON.parse(raw) as CacheEnvelope
      if (!parsed.fetched_at || !parsed.manifest) return null
      const age = now - new Date(parsed.fetched_at).getTime()
      if (Number.isNaN(age) || age < 0 || age > CACHE_TTL_MS) return null
      return parsed
    } catch {
      return null
    }
  }
  
  async function writeCache(dir: string, file: string, envelope: CacheEnvelope): Promise<void> {
    await fs.mkdir(dir, { recursive: true })
    const tmp = `${file}.tmp.${process.pid}`
    await fs.writeFile(tmp, JSON.stringify(envelope, null, 2), 'utf8')
    await fs.rename(tmp, file)
  }
  
  async function fetchLive(url: string, fetchImpl: typeof fetch): Promise<ApiManifest> {
    const controller = new AbortController()
    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
    try {
      const res = await fetchImpl(url, {
        method: 'GET',
        headers: { Accept: 'application/json' },
        signal: controller.signal,
      })
      if (!res.ok) throw new Error(`Manifest fetch failed: HTTP ${res.status}`)
      const json = (await res.json()) as ApiManifest
      if (!Array.isArray(json.endpoints)) throw new Error('Manifest missing endpoints array')
      return json
    } finally {
      clearTimeout(timer)
    }
  }
  
  function defaultFallbackPaths(): string[] {
    const scriptDir = process.argv[1] ? path.dirname(process.argv[1]) : process.cwd()
    return [
      process.env.ILETIMERKEZI_FALLBACK_MANIFEST,
      path.resolve(scriptDir, 'manifest.fallback.json'),
      path.resolve(scriptDir, '../manifest.fallback.json'),
      path.resolve(process.cwd(), 'dist/manifest.fallback.json'),
    ].filter((p): p is string => typeof p === 'string' && p.length > 0)
  }
  
  function loadFallback(overridePaths?: string[]): ApiManifest {
    const candidates = overridePaths !== undefined ? overridePaths : defaultFallbackPaths()
    for (const candidate of candidates) {
      try {
        return JSON.parse(readFileSync(candidate, 'utf8')) as ApiManifest
      } catch {
        // try next
      }
    }
    throw new Error(
      'iletiMerkezi manifest is unavailable: live fetch failed, no cache, and no fallback shipped with the package.',
    )
  }
  
  export async function loadManifest(options: LoadOptions = {}): Promise<ManifestLoadResult> {
    const url = options.manifestUrl || getManifestUrl()
    const cache = options.cacheFile
      ? { dir: options.cacheDir || path.dirname(options.cacheFile), file: options.cacheFile }
      : getCachePath()
    const now = options.now ? options.now() : Date.now()
    const fetchImpl = options.fetchImpl || globalThis.fetch
  
    const cached = await readCache(cache.file, now)
    if (cached) {
      return { manifest: cached.manifest, source: 'cache', fetched_at: cached.fetched_at }
    }
  
    try {
      const live = await fetchLive(url, fetchImpl)
      const fetched_at = new Date(now).toISOString()
      void writeCache(cache.dir, cache.file, { fetched_at, manifest: live }).catch(() => {})
      return { manifest: live, source: 'live', fetched_at }
    } catch {
      const fallback = loadFallback(options.fallbackPaths)
      return {
        manifest: fallback,
        source: 'fallback' as ManifestSource,
        fetched_at: fallback.generated_at,
      }
    }
  }

• src/server.ts:43-71 (handler)

  The CallToolRequestSchema handler in server.ts looks up the tool by name (including 'get_balance') from the toolByName map and calls executeTool() with the tool definition, arguments, and credentials.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const tool = toolByName.get(request.params.name)
    if (!tool) {
      return {
        isError: true,
        content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
      }
    }
    let credentials
    try {
      credentials = readCredentials(env)
    } catch (err) {
      const message = err instanceof MissingCredentialsError ? err.message : String(err)
      return { isError: true, content: [{ type: 'text', text: message }] }
    }
    try {
      const outcome = await executeTool(tool, request.params.arguments, {
        credentials,
        fetchImpl: options.fetchImpl,
      })
      return { isError: outcome.isError, content: [{ type: 'text', text: outcome.text }] }
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err)
      return {
        isError: true,
        content: [{ type: 'text', text: `Tool execution failed: ${message}` }],
      }
    }
  })

• src/tools.ts:50-78 (handler)

  The executeTool function is the generic handler that executes any tool (including get_balance). It calls the endpoint, processes the response, formats output, and returns structured results.

  export async function executeTool(
    tool: McpToolDefinition,
    rawInput: unknown,
    ctx: ToolCallContext,
  ): Promise<ToolCallOutcome> {
    const input = (rawInput && typeof rawInput === 'object' ? rawInput : {}) as Record<string, unknown>
    const { status, body, request_url } = await callEndpoint({
      endpoint: tool.endpoint,
      input,
      credentials: ctx.credentials,
      fetchImpl: ctx.fetchImpl,
      baseUrl: ctx.baseUrl,
    })
  
    const apiCode = extractApiStatusCode(body)
    const ok = status >= 200 && status < 300 && (apiCode === null || apiCode === 200)
    const summary = ok
      ? `iletiMerkezi ${tool.endpoint.path} succeeded (HTTP ${status}${apiCode !== null ? `, response.status.code ${apiCode}` : ''}).`
      : `iletiMerkezi ${tool.endpoint.path} failed (HTTP ${status}${apiCode !== null ? `, response.status.code ${apiCode}` : ''}).`
    const guidance = ok ? '' : guidanceFor(apiCode, tool.endpoint)
    const payload = JSON.stringify(body, null, 2)
  
    return {
      isError: !ok,
      text: [summary, guidance, `Request URL: ${request_url}`, '```json', payload, '```']
        .filter(Boolean)
        .join('\n'),
    }
  }

• src/tools.ts:11-20 (registration)

  buildToolDefinitions builds McpToolDefinition objects from manifest endpoints, creating a tool entry with name, description, inputSchema, and endpoint for each endpoint that has an mcp_tool name (including 'get_balance').

  export function buildToolDefinitions(manifest: ApiManifest): McpToolDefinition[] {
    return manifest.endpoints
      .filter((ep) => ep.mcp_tool && ep.input_schema)
      .map((ep) => ({
        name: ep.mcp_tool!,
        description: buildDescription(ep),
        inputSchema: ep.input_schema as Record<string, unknown>,
        endpoint: ep,
      }))
  }