Geliştirici Belgeleri: API ve MCP

Hesaplayıcı’daki her hesaplayıcı, sayfadaki formun kullandığı JSON API ile de çalışır ve Claude, ChatGPT ya da Cursor gibi yapay zekâ istemcilerine MCP sunucusu olarak bağlanır. Ücretsiz araçlar için hesap veya anahtar gerekmez; istekler IP adresine göre sınırlanır. Her yanıt sonucu, hesaplama adımlarını ve atıf için araç sayfasının adresini verir.

Hızlı başlangıç

Araçları listelemek ve bir aracı çalıştırmak için iki HTTP isteği yeter. Liste isteği her aracın kimliğini, adını ve sürümünü verir. Çalıştırma isteği input nesnesini aracın şemasına göre doğrular; sonucu, adımları ve atıf adresini döndürür. Aşağıdaki yanıt, sitenin her derlemesinde gerçekten çalıştırılan örnektir.

Tüm araçları listeleyin:

curl https://hesaplayici.com/api/v1/tools

Bileşik Faiz Hesaplama aracını ilk örneğiyle çalıştırın:

curl -X POST https://hesaplayici.com/api/v1/tools/finance.compound-interest/execute \
  -H 'Content-Type: application/json' \
  -d '{"input":{"principal":10000,"rate":10,"rateUnit":"yearly","years":5,"months":0,"weeks":0,"days":0,"compounding":"monthly"},"locale":"tr"}'

Yanıt:

{
  "output": {
    "finalAmount": 16453.089347785855,
    "interestEarned": 6453.089347785855,
    "annualRate": 10,
    "effectiveRate": 10.471306744129683,
    "termYears": 5,
    "yearly": [
      {
        "period": 0,
        "interest": 0,
        "accruedInterest": 0,
        "balance": 10000
      },
      {
        "period": 1,
        "interest": 1047.1306744129688,
        "accruedInterest": 1047.1306744129688,
        "balance": 11047.130674412969
      },
      {
        "period": 2,
        "interest": 1156.7789393426228,
        "accruedInterest": 2203.9096137555916,
        "balance": 12203.909613755592
      },
      {
        "period": 3,
        "interest": 1277.908810432682,
        "accruedInterest": 3481.8184241882736,
        "balance": 13481.818424188274
      },
      {
        "period": 4,
        "interest": 1411.7225618833454,
        "accruedInterest": 4893.540986071619,
        "balance": 14893.540986071619
      },
      {
        "period": 5,
        "interest": 1559.5483617142363,
        "accruedInterest": 6453.089347785855,
        "balance": 16453.089347785855
      }
    ],
    "monthly": [
      {
        "period": 0,
        "interest": 0,
        "accruedInterest": 0,
        "balance": 10000
      },
      {
        "period": 1,
        "interest": 83.33333333333394,
        "accruedInterest": 83.33333333333394,
        "balance": 10083.333333333334
      },
      {
        "period": 2,
        "interest": 84.02777777777737,
        "accruedInterest": 167.3611111111113,
        "balance": 10167.361111111111
      },
      {
        "period": 3,
        "interest": 84.7280092592573,
        "accruedInterest": 252.08912037036862,
        "balance": 10252.089120370369
      },
      {
        "period": 4,
        "interest": 85.43407600308637,
        "accruedInterest": 337.523196373455,
        "balance": 10337.523196373455
      },
      {
        "period": 5,
        "interest": 86.14602663644655,
        "accruedInterest": 423.66922300990154,
        "balance": 10423.669223009902
      },
      {
        "period": 6,
        "interest": 86.86391019174698,
        "accruedInterest": 510.5331332016485,
        "balance": 10510.533133201649
      },
      {
        "period": 7,
        "interest": 87.5877761100146,
        "accruedInterest": 598.1209093116631,
        "balance": 10598.120909311663
      },
      {
        "period": 8,
        "interest": 88.31767424426289,
        "accruedInterest": 686.438583555926,
        "balance": 10686.438583555926
      },
      {
        "period": 9,
        "interest": 89.05365486296796,
        "accruedInterest": 775.492238418894,
        "balance": 10775.492238418894
      },
      {
        "period": 10,
        "interest": 89.79576865348827,
        "accruedInterest": 865.2880070723822,
        "balance": 10865.288007072382
      },
      {
        "period": 11,
        "interest": 90.54406672560435,
        "accruedInterest": 955.8320737979866,
        "balance": 10955.832073797987
      },
      {
        "period": 12,
        "interest": 91.2986006149822,
        "accruedInterest": 1047.1306744129688,
        "balance": 11047.130674412969
      },
      {
        "period": 13,
        "interest": 92.05942228677304,
        "accruedInterest": 1139.1900966997418,
        "balance": 11139.190096699742
      },
      {
        "period": 14,
        "interest": 92.82658413916579,
        "accruedInterest": 1232.0166808389076,
        "balance": 11232.016680838908
      },
      {
        "period": 15,
        "interest": 93.6001390069905,
        "accruedInterest": 1325.6168198458981,
        "balance": 11325.616819845898
      },
      {
        "period": 16,
        "interest": 94.38014016538182,
        "accruedInterest": 1419.99696001128,
        "balance": 11419.99696001128
      },
      {
        "period": 17,
        "interest": 95.16664133342601,
        "accruedInterest": 1515.163601344706,
        "balance": 11515.163601344706
      },
      {
        "period": 18,
        "interest": 95.95969667787358,
        "accruedInterest": 1611.1232980225795,
        "balance": 11611.12329802258
      },
      {
        "period": 19,
        "interest": 96.75936081685359,
        "accruedInterest": 1707.8826588394331,
        "balance": 11707.882658839433
      },
      {
        "period": 20,
        "interest": 97.56568882366082,
        "accruedInterest": 1805.448347663094,
        "balance": 11805.448347663094
      },
      {
        "period": 21,
        "interest": 98.37873623052656,
        "accruedInterest": 1903.8270838936205,
        "balance": 11903.82708389362
      },
      {
        "period": 22,
        "interest": 99.1985590324457,
        "accruedInterest": 2003.0256429260662,
        "balance": 12003.025642926066
      },
      {
        "period": 23,
        "interest": 100.02521369105125,
        "accruedInterest": 2103.0508566171175,
        "balance": 12103.050856617117
      },
      {
        "period": 24,
        "interest": 100.85875713847418,
        "accruedInterest": 2203.9096137555916,
        "balance": 12203.909613755592
      },
      {
        "period": 25,
        "interest": 101.69924678129792,
        "accruedInterest": 2305.6088605368896,
        "balance": 12305.60886053689
      },
      {
        "period": 26,
        "interest": 102.54674050447284,
        "accruedInterest": 2408.1556010413624,
        "balance": 12408.155601041362
      },
      {
        "period": 27,
        "interest": 103.4012966753453,
        "accruedInterest": 2511.5568977167077,
        "balance": 12511.556897716708
      },
      {
        "period": 28,
        "interest": 104.2629741476394,
        "accruedInterest": 2615.819871864347,
        "balance": 12615.819871864347
      },
      {
        "period": 29,
        "interest": 105.1318322655352,
        "accruedInterest": 2720.9517041298823,
        "balance": 12720.951704129882
      },
      {
        "period": 30,
        "interest": 106.00793086774866,
        "accruedInterest": 2826.959634997631,
        "balance": 12826.959634997631
      },
      {
        "period": 31,
        "interest": 106.89133029164623,
        "accruedInterest": 2933.850965289277,
        "balance": 12933.850965289277
      },
      {
        "period": 32,
        "interest": 107.78209137741032,
        "accruedInterest": 3041.6330566666875,
        "balance": 13041.633056666687
      },
      {
        "period": 33,
        "interest": 108.680275472223,
        "accruedInterest": 3150.3133321389105,
        "balance": 13150.31333213891
      },
      {
        "period": 34,
        "interest": 109.58594443448783,
        "accruedInterest": 3259.8992765733983,
        "balance": 13259.899276573398
      },
      {
        "period": 35,
        "interest": 110.49916063811179,
        "accruedInterest": 3370.39843721151,
        "balance": 13370.39843721151
      },
      {
        "period": 36,
        "interest": 111.41998697676354,
        "accruedInterest": 3481.8184241882736,
        "balance": 13481.818424188274
      },
      {
        "period": 37,
        "interest": 112.34848686823534,
        "accruedInterest": 3594.166911056509,
        "balance": 13594.166911056509
      },
      {
        "period": 38,
        "interest": 113.284724258805,
        "accruedInterest": 3707.451635315314,
        "balance": 13707.451635315314
      },
      {
        "period": 39,
        "interest": 114.22876362762509,
        "accruedInterest": 3821.680398942939,
        "balance": 13821.680398942939
      },
      {
        "period": 40,
        "interest": 115.18066999119037,
        "accruedInterest": 3936.8610689341294,
        "balance": 13936.86106893413
      },
      {
        "period": 41,
        "interest": 116.14050890778526,
        "accruedInterest": 4053.0015778419147,
        "balance": 14053.001577841915
      },
      {
        "period": 42,
        "interest": 117.1083464820149,
        "accruedInterest": 4170.10992432393,
        "balance": 14170.10992432393
      },
      {
        "period": 43,
        "interest": 118.08424936936717,
        "accruedInterest": 4288.194173693297,
        "balance": 14288.194173693297
      },
      {
        "period": 44,
        "interest": 119.0682847807766,
        "accruedInterest": 4407.262458474073,
        "balance": 14407.262458474073
      },
      {
        "period": 45,
        "interest": 120.0605204872827,
        "accruedInterest": 4527.322978961356,
        "balance": 14527.322978961356
      },
      {
        "period": 46,
        "interest": 121.06102482467941,
        "accruedInterest": 4648.3840037860355,
        "balance": 14648.384003786035
      },
      {
        "period": 47,
        "interest": 122.06986669821526,
        "accruedInterest": 4770.453870484251,
        "balance": 14770.45387048425
      },
      {
        "period": 48,
        "interest": 123.08711558736832,
        "accruedInterest": 4893.540986071619,
        "balance": 14893.540986071619
      },
      {
        "period": 49,
        "interest": 124.11284155059548,
        "accruedInterest": 5017.6538276222145,
        "balance": 15017.653827622215
      },
      {
        "period": 50,
        "interest": 125.14711523018377,
        "accruedInterest": 5142.800942852398,
        "balance": 15142.800942852398
      },
      {
        "period": 51,
        "interest": 126.19000785710341,
        "accruedInterest": 5268.990950709502,
        "balance": 15268.990950709502
      },
      {
        "period": 52,
        "interest": 127.24159125591177,
        "accruedInterest": 5396.2325419654135,
        "balance": 15396.232541965413
      },
      {
        "period": 53,
        "interest": 128.30193784971198,
        "accruedInterest": 5524.534479815125,
        "balance": 15524.534479815125
      },
      {
        "period": 54,
        "interest": 129.371120665126,
        "accruedInterest": 5653.905600480251,
        "balance": 15653.905600480251
      },
      {
        "period": 55,
        "interest": 130.4492133373351,
        "accruedInterest": 5784.354813817587,
        "balance": 15784.354813817587
      },
      {
        "period": 56,
        "interest": 131.5362901151475,
        "accruedInterest": 5915.891103932734,
        "balance": 15915.891103932734
      },
      {
        "period": 57,
        "interest": 132.6324258661025,
        "accruedInterest": 6048.5235297988365,
        "balance": 16048.523529798837
      },
      {
        "period": 58,
        "interest": 133.7376960816582,
        "accruedInterest": 6182.261225880495,
        "balance": 16182.261225880495
      },
      {
        "period": 59,
        "interest": 134.8521768823357,
        "accruedInterest": 6317.11340276283,
        "balance": 16317.11340276283
      },
      {
        "period": 60,
        "interest": 135.9759450230249,
        "accruedInterest": 6453.089347785855,
        "balance": 16453.089347785855
      }
    ],
    "truncated": false
  },
  "steps": [
    {
      "id": "annualRate",
      "formula": "r = oran × yıldaki dönem sayısı",
      "substitution": "r = %10 × 1",
      "value": 10,
      "unit": "%"
    },
    {
      "id": "termYears",
      "formula": "t = yıl + ay/12 + hafta/52 + gün/365",
      "substitution": "t = 5 + 0/12 + 0/52 + 0/365",
      "value": 5,
      "unit": "yıl"
    },
    {
      "id": "finalAmount",
      "formula": "A = P × (1 + r/n)^(n × t)",
      "substitution": "A = 10.000 × (1 + %10/12)^(12 × 5)",
      "value": 16453.089347785855
    },
    {
      "id": "effectiveRate",
      "formula": "e = (1 + r/n)^n − 1",
      "substitution": "e = (1 + %10/12)^12 − 1",
      "value": 10.471306744129683,
      "unit": "%"
    }
  ],
  "meta": {
    "toolVersion": "1.0.0",
    "locale": "tr"
  },
  "citation": {
    "url": "https://hesaplayici.com/finans/bilesik-faiz-hesaplama",
    "title": "Bileşik Faiz Hesaplama"
  }
}

Kimlik doğrulama

Bugün ücretsiz araçlar anonim kullanılır; istekte kimlik bilgisi gerekmez. API anahtarları ve MCP için OAuth, ücretli araçlarla birlikte gelecek. O zaman anahtar Authorization: Bearer başlığıyla gönderilecek; çerez hiçbir zaman kullanılmaz.

İstek sınırı

Her IP adresi dakikada sınırlı sayıda hesaplama yapabilir. Yalnızca çalıştırma istekleri sınırdan düşer: REST’te execute, MCP’de tools/call. Liste, şema ve kaynak okuma istekleri düşmez. Her yanıt, sınırı ve kalan hakkı başlıklarda bildirir.

Anonim istekler: IP adresi başına 60 saniyede 60 hesaplama.

Başlık	Açıklama
`X-RateLimit-Limit`	Penceredeki hesaplama hakkı
`X-RateLimit-Remaining`	Penceredeki kalan hak
`X-RateLimit-Reset`	Pencerenin yenilendiği an (Unix saniyesi)
`Retry-After`	Yalnızca 429 yanıtında: yeniden denemeden önce beklenecek saniye

Sınır aşılınca yanıtın durumu 429 olur:

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit reached. Try again after Retry-After seconds."
}

Hatalar

Hatalar RFC 9457 problem ayrıntısı biçimindedir (application/problem+json). Her hatanın değişmeyen bir code alanı vardır. Girdi hatalarında errors dizisi hangi alanın neden reddedildiğini söyler; bilinmeyen bir girdi alanı da hatadır. MCP’de aynı nesne, isError işaretli sonucun structuredContent alanında gelir.

MCP

Ağ geçidi sunucusu tüm araçlara üç araçla ulaşır: search_tools aracı bulur, get_tool şemasını verir, run_tool aracı çalıştırır. Kategori sunucuları ise o kategorideki her aracı doğrudan kendi şemasıyla sunar. Araç sayfaları ve rehberler Markdown kaynağı olarak da okunur.

Sunucu	Adres
Ağ geçidi (tüm araçlar)	`https://hesaplayici.com/mcp`
Finans	`https://hesaplayici.com/mcp/finance`
Sağlık	`https://hesaplayici.com/mcp/health`
Konut	`https://hesaplayici.com/mcp/housing`
Maaş & İş	`https://hesaplayici.com/mcp/labor`
Matematik	`https://hesaplayici.com/mcp/math`
Vergi	`https://hesaplayici.com/mcp/tax`
Zaman	`https://hesaplayici.com/mcp/time`
Birim Çevirici	`https://hesaplayici.com/mcp/units`

Ağ geçidinin araçları: search_tools, get_tool, run_tool

Claude Code

Terminalde çalıştırın:

claude mcp add --transport http hesaplayici https://hesaplayici.com/mcp

claude.ai

Ayarlar › Bağlayıcılar › Özel bağlayıcı ekle; adres olarak şunu girin:

https://hesaplayici.com/mcp

Claude Desktop (claude_desktop_config.json)

Yapılandırma dosyasına ekleyin; mcp-remote köprüsü sunucuya HTTP ile bağlanır:

{
  "mcpServers": {
    "hesaplayici": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://hesaplayici.com/mcp"
      ]
    }
  }
}

Cursor (.cursor/mcp.json)

Proje klasöründeki dosyaya ekleyin:

{
  "mcpServers": {
    "hesaplayici": {
      "url": "https://hesaplayici.com/mcp"
    }
  }
}

VS Code (.vscode/mcp.json)

Proje klasöründeki dosyaya ekleyin:

{
  "servers": {
    "hesaplayici": {
      "type": "http",
      "url": "https://hesaplayici.com/mcp"
    }
  }
}

ChatGPT

Ayarlarda geliştirici modunu açın, bu adresle bir bağlayıcı oluşturun; kimlik doğrulama: yok.

https://hesaplayici.com/mcp

MCP Inspector

MCP Inspector ile deneyin:

npx -y @modelcontextprotocol/inspector --cli https://hesaplayici.com/mcp --transport http --method tools/list

Araç başvurusu

Her aracın girdi alanları, sınırları, varsayılanları ve çıktıları araç tanımından üretilir, bu yüzden her aracın başvuru sayfası her derlemede kodla aynıdır. Aracın sayfasını aşağıdaki listeden açın.

Araç	Kimlik	Erişim
Ağırlık Çevirici	`units.weight`	Ücretsiz
Basit Faiz Hesaplama	`finance.simple-interest`	Ücretsiz
Bileşik Faiz Hesaplama	`finance.compound-interest`	Ücretsiz
Brüt Net Maaş Hesaplama	`labor.gross-to-net.tr`	Ücretsiz
Damga Vergisi Hesaplama	`tax.stamp-duty.tr`	Ücretsiz
Emlak Komisyonu Hesaplama	`housing.real-estate-commission.tr`	Ücretsiz
Faiz Hesaplama	`finance.interest`	Ücretsiz
Fazla Mesai Hesaplama	`labor.overtime.tr`	Ücretsiz
Gelir Vergisi Hesaplama	`tax.income-tax.tr`	Ücretsiz
Gün Sayacı Hesaplama	`time.day-counter`	Ücretsiz
Günlük Kalori İhtiyacı Hesaplama	`health.calorie`	Ücretsiz
İdeal Kilo Hesaplama	`health.ideal-weight`	Ücretsiz
İhbar Tazminatı Hesaplama	`labor.notice-pay.tr`	Ücretsiz
İki Tarih Arası Gün Hesaplama	`time.date-difference`	Ücretsiz
Karekök Hesaplama	`math.square-root`	Ücretsiz
KDV Hesaplama	`tax.vat.tr`	Ücretsiz
Kesir Sadeleştirme	`math.fraction`	Ücretsiz
Kıdem Tazminatı Hesaplama	`labor.severance.tr`	Ücretsiz
Kira Artış Oranı Hesaplama	`housing.rent-increase.tr`	Ücretsiz
Kredi Erken Ödeme Hesaplama	`finance.early-repayment.tr`	Ücretsiz
Kredi Hesaplama	`finance.loan-payment.tr`	Ücretsiz
Kredi Kartı Asgari Ödeme Hesaplama	`finance.credit-card-minimum.tr`	Ücretsiz
Mevduat Faizi Hesaplama	`finance.deposit-interest.tr`	Ücretsiz
Net Brüt Maaş Hesaplama	`labor.net-to-gross.tr`	Ücretsiz
Oran Orantı Hesaplama	`math.ratio`	Ücretsiz
Sabit Oranlı Enflasyon Hesaplama	`finance.inflation`	Ücretsiz
Sıcaklık Çevirici	`units.temperature`	Ücretsiz
Stopaj Hesaplama	`tax.withholding.tr`	Ücretsiz
Su İhtiyacı Hesaplama	`health.water-intake`	Ücretsiz
Tapu Harcı Hesaplama	`housing.title-deed-fee.tr`	Ücretsiz
Uzunluk Çevirici	`units.length`	Ücretsiz
Vücut Kitle İndeksi Hesaplama	`health.bmi`	Ücretsiz
Vücut Yağ Oranı Hesaplama	`health.body-fat`	Ücretsiz
Yaş Hesaplama	`time.age`	Ücretsiz
Yatırım Getirisi Hesaplama	`finance.investment-return`	Ücretsiz
Yüzde Değişim Hesaplama	`math.percentage-change`	Ücretsiz
Yüzde Hesaplama	`math.percentage`	Ücretsiz