# Нишка (Nishka)

> Nishka is a Bulgarian civic assistant. Its open layer gives AI agents and developers checked facts about Bulgarian public services, Bulgarian legal deadlines and working days, and official documents from primary sources, each with its official source and date. Read-only, no account, no key.

Pages for people are in Bulgarian; the data is mostly Bulgarian, so query in Bulgarian. Cite the official source URL of every fact you use, with its check or publication date. When nothing is found, say so; do not guess contacts, fees or deadlines.

## Connect an agent

- [MCP server](https://nishka.app/mcp): Streamable HTTP, stateless, one JSON answer per POST. MCP 2026-07-28 (no handshake) and 2025-11-25, 2025-06-18, 2025-03-26 (initialize). Tools for Основа, Срок and Извор; resources osnova://entry/{id} and izvor://document/{id}; prompts civic_question and deadline_from_letter.
- [Server card](https://nishka.app/mcp/server-card): the MCP Server Card.
- [AI Catalog](https://nishka.app/.well-known/ai-catalog.json): domain-level discovery.
- [Guide for developers](https://nishka.app/razrabotchitsi): in Bulgarian; how to connect, the tools, limits, licences, how to cite.

## APIs

- [OpenAPI 3.1](https://nishka.app/openapi.json): every REST endpoint below.
- [Основа](https://nishka.app/osnova): checked facts about institutions, offices, procedures and fees in Plovdiv, Sofia, Varna and Burgas; 113 entries, 477 facts, CC BY 4.0. API under https://nishka.app/osnova/v0/.
- [Срок](https://nishka.app/srok): Bulgarian working days and deadline counting (ГПК чл. 60), with the reason and legal basis of every step. API under https://nishka.app/srok/v0/.
- [Извор](https://nishka.app/izvor): an index of Bulgarian primary official sources (State Gazette, municipal council decisions, public procurement) with the official URL of every record. API under https://nishka.app/izvor/v0/.

## Downloads

- [osnova.json](https://nishka.app/osnova/v0/osnova.json): the whole Основа dataset.
- [facts.csv](https://nishka.app/osnova/v0/facts.csv): every Основа fact, one per row.
- [manifest.json](https://nishka.app/osnova/v0/manifest.json): version, licence, counts, content hash and the latest check date.

## Licences and citing

- Основа: CC BY 4.0. Attribute „Основа, проверени данни на Нишка (nishka.app), CC BY 4.0“ and cite the official source and check date of each fact.
- Извор and Срок point to official records and laws; the official text at the cited URL is authoritative. Bulgarian acts of state bodies are not subject to copyright (ЗАПСП чл. 4, т. 1).
- Nothing here is legal advice.

## Optional

- [Full reference for agents](https://nishka.app/llms-full.txt): every tool with its parameters, the citation fields, the sources Извор covers.
- [БГ-бенч](https://nishka.app/bench): how well AI models answer Bulgarian civic questions.

## Server instructions

Нишка (nishka.app) е български граждански помощник. Това е откритият ѝ слой: проверени факти за институции и услуги (Основа), законови срокове и работни дни (Срок) и официални документи от първични източници (Извор). Само четене, без регистрация.

Цитирайте всеки използван факт: адреса на официалния източник (citations[].url) и датата на проверка или публикуване. Когато няма намерен запис, кажете го и насочете към институцията; не предполагайте контакти, такси или срокове.

Nishka (nishka.app) is a Bulgarian civic assistant. This is its open layer: checked facts about public services in Plovdiv, Sofia, Varna and Burgas (Основа, CC BY 4.0), Bulgarian legal deadlines and working days (Срок), and an index of official primary sources such as the State Gazette and council decisions (Извор). Read-only, no account.

Every result carries citations: cite citations[].url and give checkedOn or publishedOn. Query in Bulgarian. If nothing is found, say so and point to the institution; never guess contacts, fees or deadlines. Answer people in Bulgarian with the polite „Вие“ unless they write in another language.

## Tools

All tools only read and give the same answer to the same call. Each returns text a model can quote and the same data as structuredContent, described by the tool's outputSchema.

### search_osnova (Търсене в Основа)

Search Основа, checked facts about Bulgarian public services (institutions, offices, contacts, procedures, fees, where to report a problem), for Plovdiv, Sofia, Varna and Burgas. Query in Bulgarian works best. Every fact has its official source and the date it was checked; cite them.

  - `query` (string, required): What to look for, e.g. „лична карта“, „дупка на пътя“, „ВиК авария“.
  - `city` (string): Limit to one city. One of: plovdiv, sofia, varna, burgas.
  - `kind` (string): service: an institution or office; rule: a procedure. One of: service, rule.
  - `limit` (integer)

### get_osnova_entry (Запис от Основа)

One Основа entry by its id (city/kind/slug), with all its facts, sources and check dates.

  - `id` (string, required): e.g. „plovdiv/service/…“, as search_osnova returns it.

### about_osnova (За Основа)

What Основа covers: cities, counts, licence (CC BY 4.0), how to cite it and when it was last checked.

  - no parameters

### srok_deadline (Срок: последен ден)

Count a Bulgarian legal deadline the way the Civil Procedure Code does (ГПК чл. 60): days count from the day after the event; weeks, months and years end on the corresponding date; an end on a non-working day moves to the next working day. Returns the last day and each step with its reason. Other laws can have their own rules: tell the user to check the letter or the law.

  - `from` (string, required): The day of the event the deadline runs from, YYYY-MM-DD (e.g. the day a letter was received).
  - `amount` (integer, required)
  - `unit` (string, required) One of: days, weeks, months, years, working_days.

### srok_day (Срок: работен ли е денят)

Whether a date is a working day in Bulgaria, and if not, why (official holiday, the day after a weekend holiday, a government decision, or a weekend).

  - `date` (string, required): YYYY-MM-DD

### srok_year (Срок: календар за година)

Every non-working weekday and every working Saturday in a year in Bulgaria (2020–2099), with the legal basis.

  - `year` (integer, required)

### search_izvor (Търсене в Извор)

Search Извор, an index of Bulgarian primary official sources (e.g. the State Gazette, municipal council decisions, public procurement notices). Returns the official record's title, issuer, number, date and official URL. Cite the official URL, not Извор; the excerpt is for orientation only.

  - `query` (string, required): Words to find, in Bulgarian, e.g. „бюджет 2027“, „решение ремонт улица“.
  - `source` (string): Limit to one source id (see about_izvor).
  - `from` (string): Earliest publication date, YYYY-MM-DD.
  - `to` (string): Latest publication date, YYYY-MM-DD.
  - `limit` (integer)

### get_izvor_document (Документ от Извор)

One Извор record by id, with its full stored excerpt and when Nishka first and last saw it.

  - `id` (string, required): e.g. „dv:…“, as search_izvor returns it.

### about_izvor (За Извор)

Which sources Извор covers, how many records each has, and when each was last collected.

  - no parameters

## Citations

Every successful tool result has `structuredContent.citations`, a list of:

- `id`: stable id in the open layer (osnova:…, izvor:…, srok:…)
- `title`, `url`: the official source; cite this URL
- `publisher`: the issuing institution, when known
- `publishedOn`: the date the source gives the document (YYYY-MM-DD)
- `checkedOn`: the day Nishka last checked it against the source (YYYY-MM-DD, Bulgarian calendar)
- `licence`: CC-BY-4.0 (Основа) or official-record (an official document or act)
- `record`: Nishka's machine-readable record, when there is one

## Resources

- `osnova://entry/{+id}`: One Основа entry (city/kind/slug) with its facts, official sources and check dates. CC BY 4.0.
- `izvor://document/{id}`: One Извор record (source:id): title, issuer, number, date, official URL and the stored excerpt.

`resources/list` lists the Основа entries, 100 per page.

## Prompts

- `civic_question`: Answer a Bulgarian civic question (where to go, whom to write to, what it costs) from Основа and Извор, with cited official sources. Arguments: question (required), city.
- `deadline_from_letter`: Work out the last day to act after receiving an official letter or decision, with each step of the count. Arguments: received_on (required), period (required).

## Sources Извор covers

- `parliament`: Народно събрание – закони и решения (https://www.parliament.bg/bg/laws)
- `eop`: Обществени поръчки (ЦАИС ЕОП) (https://app.eop.bg/today)
- `dv`: Държавен вестник – официален раздел (https://dv.parliament.bg/)
- `plovdiv-council`: Общински съвет – Пловдив – решения (https://plovdiv.bg/obs/)

## Example (MCP 2026-07-28)

```
POST https://nishka.app/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search_osnova

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_osnova","arguments":{"query":"лична карта","city":"plovdiv"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28"}}}
```

Clients on 2025-11-25 or earlier send `initialize` first and then the same calls without `_meta`.