# Submission guide for mcpfarsi.ir

This file lists the standards for MCP servers and Agent Skills in the mcpfarsi.ir marketplace. Give it to your AI assistant so it can check and improve your tool before you submit it. The assistant can also keep this file as working context.

mcpfarsi.ir is a Persian (RTL) marketplace for Iranian users, so the catalog content itself is Persian. The `name`, `summary` and the full description (`body`) must be written in Persian. Give `nameEn` in English. Example prompts (`prompts`) are Persian too. Everything else in this guide (code, commands, field names) stays as it is. Persian UI terms that the site itself shows, such as «قابلیت» (capability: one function of a server) and «ابزار» (tool: one item in the marketplace), are kept in Persian below next to an English explanation.

## Prompt to give your assistant

```
This file is the submission guide for mcpfarsi.ir. Read my project's code (an MCP server or a skill) and compare it with every section of the guide.
1. List every rule that is not met, with the file name and line.
2. Fix the safe ones yourself and ask me about the rest.
3. Do not invent anything: capability names, install commands and the license must come only from the real code and repository.
4. At the end, give me ready-to-paste text for the submission form fields: Persian name, English name, id, summary, category, tags, warnings, example prompts and full description. Write the Persian name, summary, example prompts and description in Persian.
```

## Form fields and limits

These limits are checked both in the form and in the site build (`site/src/lib/catalog-schema.js`).

| Field | Rule |
|---|---|
| `name` / `nameEn` | Up to 80 characters. `name` is the Persian name and must not contain the maker's name; the maker goes in `author`. `nameEn` is the English name. |
| `id` | Lowercase English letters, digits and hyphens only (for example `kavenegar`). The page URL is built from it. |
| `summary` | Persian. At most 150 characters, because it becomes the page's meta description (the form accepts up to 160, but keep to 150). Never end it with «…». |
| `category` | One of the categories listed in the form. |
| `tags` | At most 10 tags, each up to 30 characters. |
| `author.name`, `author.url` | Name up to 80 characters; the URL must be `http(s)` only. |
| `repo`, `homepage` | `http(s)` URL, up to 2000 characters. |
| `license` | Up to 40 characters, for example `MIT`. |
| `prompts` | Example prompts in Persian, at most 10, each up to 200 characters. Each one is a sentence the user says to the assistant. |
| `tools` | The server's capabilities («قابلیت»); at most 50. Name up to 80 and description up to 300 characters. |
| `body` | Full description in Persian, written in Markdown, at most 5000 characters. No raw HTML, no level-one heading, links `http(s)` only. |
| Logo | PNG, JPEG or WebP, at most 200 KB. SVG is not accepted. |

### Install command (MCP server)

- `stdio`: `command` is required and `args` has at most 30 items (each up to 300 characters).
- `http`: `url` is required. `headers` has at most 10 entries. Write a key as `${NAME}` and define the same `NAME` in `env`.
- `env`: at most 20 variables. The name uses only uppercase English letters, digits and underscores (`KAVENEGAR_API_KEY`); the description is up to 300 characters. Mark keys as `secret`.
- In `command`, `args`, `url` and `headers`, a single quote (`'`), curly quotes ‘ ’ and control characters are not allowed, because these values are pasted into a shell inside single quotes.

## MCP server standard

- JavaScript ESM or Python only, with stdio or HTTP transport. With stdio, write nothing but the protocol to stdout; send logs to stderr (`console.error`).
- Every network request has a 20-second timeout (`AbortSignal.timeout(20000)` or the equivalent) and sends a browser-like `User-Agent`.
- Never throw errors. Return them as `{ isError: true, content: [...] }` with a clear message: what happened and what the user should do.
- Mark read-only tools with `readOnlyHint: true`. In "read-only" mode, the MCP router keeps only these.
- Put pure logic in a separate module and write tests for it. `server.js` must have no side effects on import (no transport connection or network request at the top level of the file).
- Capability names are English `snake_case`, and their descriptions are clear: what it does and when to call it. Count the capabilities from the server itself (`tools/list`), not from the README.
- Keep the number of capabilities small and useful, and trim output to what is needed.
- The server must really work; the site admin tries it before approving.

## Honest warnings

These three flags become warnings next to the tool on the site. Set them correctly:

- `unofficialApi`: the tool uses an unofficial or reverse-engineered API of the service.
- `needsIranIp`: it works only from an Iranian IP.
- `sideEffects`: it can cost money or change account data (for example sending an SMS or making a purchase).

## Skill standard

A skill is a folder with a `SKILL.md` file. The file starts with a frontmatter section:

```markdown
---
name: persian-writing
description: چه کاری انجام می‌دهد و دستیار چه زمانی باید از آن استفاده کند.
---

# عنوان

متن دستورالعمل…
```

(The example above is Persian on purpose: it shows what a skill for Persian users looks like. Replace the text with your own.)

- `name` is the same as the folder name: lowercase English letters and hyphens.
- `description` says what the skill does and in which situations it should be activated. The assistant uses this text to decide whether to load the skill.
- Keep the text short and practical. Put long material in separate `.md` files and point to them from `SKILL.md`.
- When uploading in the form: 1 to 10 `.md` files, one of them `SKILL.md`. File names use only English letters, digits, `_` and `-` (folders are separated with `/`). Each file is up to 100 KB and the total is up to 300 KB.
- If your skill does not come as files, you can give an "install command" instead (up to 500 characters), such as the one in the repository's README.

## Writing the Persian text

- «قابلیت» (capability) is for the functions of one server; «ابزار» (tool) is for one item in the marketplace. Use both correctly.
- Your reader is an ordinary user: short sentences, active verbs, no needlessly Arabic-style or technical words. Say «دستیار» (assistant) or «برنامه هوش مصنوعی» (AI app), not «مدل» (model) or «کلاینت» (client).
- Write the half-space (ZWNJ) correctly (می‌کند, not «میکند»). Numbers in Persian text use Persian digits (۱۲۳); in code, commands and URLs use Latin digits.
- Keep product names, code and commands in Latin script.
- Everything you write must be real: take capability names, install commands, license and star counts only from the real source. Leave blank anything you cannot verify.

## Checklist before submitting

- [ ] The repository is public and has a license.
- [ ] The server really runs and its capability list matches `tools/list`.
- [ ] Nothing but the protocol is written to stdout.
- [ ] 20-second timeout and returning errors with `isError` in every network call.
- [ ] Keys are in `env` marked `secret`, with no real value in the code or repository.
- [ ] The three warnings (`unofficialApi`, `needsIranIp`, `sideEffects`) are set correctly.
- [ ] `summary` is at most 150 characters and has no «…».
- [ ] At least one Persian example prompt and a full description are written.
