PassByYou888PassByYou888/LingoFuse-Tools/llms.txt

LingoFuse-Tools

llms.txt2 starsChanged 8 days agoMITView on GitHub

Machine-readable index for AI agents and LLM crawlers. This file tells an LLM what this repository does, which documents are authoritative, and in what order to read them. LingoFuse-Tools is the interface generation layer of the LingoFuse cross-language communication foundation. It solves one problem: a cross-language interface is expensive to maintain, not expensive to write once. One Add(a, b: Integer): Integer must exist in Python, C++, C#, Rust, Go, Java, JS, TS, Erlang, Julia, Zig, Swift, Ruby, Fortran, Dart, R…

The file

We split this llms.txt into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Read the KB for the tool you intend to use.
line 55
Distinctive:
Before feeding a declaration to any tool, read the corresponding rule document.
line 65
Distinctive:
Only three normalized type families.
line 114
Distinctive:
Every generated artifact is paired with a Markdown companion.
line 155
Very specific:
Add GUI tab sheets and their TSynEdit controls to the .lfm.
line 171
Very specific:
Add Convert tools and Readers to the MCP provider.
line 172
Very specific:
Add an LF_RegisterCallEx in RegisterAPIs.
line 180
Very specific:
Add the ToolDef assembly + RegisterTool(ToolDef) call in RegisterTools.
line 181
Very specific:
Update the regCount assertion.
line 182
Very specific:
Generator naming pattern: every target language contributes <lang>_abi_service_generator_tool.pas and <lang>_abi_call_generator_tool.pas.
line 274
Distinctive:
Only repositories that are part of the LingoFuse ecosystem:
line 356

≈ “Common” is an estimate: at least 1 in 5 of the 3,592 llms.txt files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

llms.txt

# llms.txt — LingoFuse-Tools

> **Machine-readable index for AI agents and LLM crawlers.**
> This file tells an LLM what this repository does, which documents are authoritative, and in what order to read them.

---

## 1. What This Repository Is

**LingoFuse-Tools** is the **interface generation layer** of the [LingoFuse](https://github.com/PassByYou888/LingoFuse) cross-language communication foundation.

It solves one problem: **a cross-language interface is expensive to maintain, not expensive to write once.** One `Add(a, b: Integer): Integer` must exist in Python, C++, C#, Rust, Go, Java, JS, TS, Erlang, Julia, Zig, Swift, Ruby, Fortran, Dart, R — plus tests, build scripts, and docs. Change the signature once, and every language can silently drift out of alignment.

LingoFuse-Tools turns the interface from a **maintenance burden** into a **generated artifact**. You maintain **one declaration** (a Pascal unit or a C header). The toolchain projects it onto every target language, every protocol, every test and build script. Change the declaration, regenerate, all targets refresh together. **There is no hand-maintained per-language copy that can drift, because there is no hand-maintained per-language copy.**

**Three tools, three protocols, one input contract:**

| Tool | Protocol | Directory |
|------|----------|-----------|
| `code_decl_to_abi` | LingoFuse binary ABI | `src/pascal_c_to_abi/` |
| `code_decl_to_json_abi` | HTTP + JSON (via `bridge.py`) | `src/pascal_c_to_json_abi/` |
| `code_decl_to_mcp` | Model Context Protocol | `src/pascal_c_to_mcp/` |

**Every tool supports three entry points** — GUI, CLI, and MCP API — and **ships with a self-contained knowledge base** for full AI takeover. GUI/CLI/MCP outputs are byte-identical; MCP `internal_call_*` calls the same handlers the GUI uses.

---

## 2. The Three Tool Lines: How to Choose

| Scenario | Tool |
|---|---|
| Both ends can load the LingoFuse runtime; numeric/string-heavy payloads; high concurrency | `code_decl_to_abi` |
| One end is a browser, an external HTTP client, or a language with no LingoFuse binding | `code_decl_to_json_abi` |
| The function should become an MCP tool an AI agent can discover | `code_decl_to_mcp` |

**Language coverage (deduplicated):** 20 target languages. `code_decl_to_abi` covers 17 with both Service and Call. `code_decl_to_json_abi` covers 20 with both Service and Call, **except** JavaScript (browser), PHP, and Delphi which are **Call-only**. `code_decl_to_mcp` covers 4 (Pascal, Python, C++, C#).

**Delphi, PHP, and JavaScript (browser) appear only in the JSON line, and only on the Call side.** They have no Service generation and no ABI/MCP generator.

---

## 3. Authoritative Documents — Read in This Order

An LLM agent should read the following documents **in order**. Each document is written to be consumed without reading the tool's source code.

### Step 1 — Project-level overview

| Document | Path | Purpose |
|----------|------|---------|
| **README** | `README.md` | Repository purpose, three tools, three entry points, quick start, ecosystem |
| **Toolchain knowledge base** | `src/pascal_c_to_mcp/code_decl_to_mcp_knowledge_base.md` | Developer-facing KB for the MCP generator; covers all generators' shared logic |

### Step 2 — Tool-specific knowledge bases

Read the KB for the tool you intend to use.

| Tool | Knowledge base | User guide |
|------|----------------|------------|
| `code_decl_to_abi` | `src/pascal_c_to_abi/code_decl_to_abi_OPERATIONS.md` | `src/pascal_c_to_abi/code_decl_to_abi_USER_GUIDE.md` |
| `code_decl_to_json_abi` | `src/pascal_c_to_json_abi/code_decl_to_json_abi_knowledge_base.md` | `src/pascal_c_to_json_abi/code_decl_to_json_abi_USER_GUIDE.md` |
| `code_decl_to_mcp` | `src/pascal_c_to_mcp/code_decl_to_mcp_knowledge_base.md` | `src/pascal_c_to_mcp/code_generate_mcp.md` |

### Step 3 — Declaration rules (parsing contracts)

Before feeding a declaration to any tool, read the corresponding rule document. **These documents ARE the parsing contract** — anything that violates them is silently dropped.

| Source language | Rule document |
|-----------------|---------------|
| Pascal | `src/pascal_c_to_abi/pascal_code_abi_rule.md` |
| C | `src/pascal_c_to_abi/C_code_abi_rule.md` |
| MCP-specific contracts | `src/pascal_c_to_mcp/MCP_API_Contract.md` |

> **Silently dropped** means: not "partially generated", not "runtime error", but **the entire declaration is excluded during normalization**. The generator logs a reason; it does not emit a broken artifact.

### Step 4 — Tool description authoring (critical for agents)

| Document | Path | Purpose |
|----------|------|---------|
| **Writing Tool Descriptions for AI** | `src/pascal_c_to_mcp/code_generate_mcp.md` §10 | **THE MOST IMPORTANT CHAPTER.** Explains why AI agents stall on ambiguous tool descriptions and how to write descriptions that agents can act on. |

---

## 4. Canonical Q&A for Agents

### Q: What does this repository do?

A: It generates cross-language binding code. Give it a Pascal unit or C header; it produces service-side and caller-side code for multiple target languages, plus a companion Markdown README for every artifact.

### Q: What is the "single source of truth"?

A: `TPascal_Func_Model` (the LV1 intermediate model). Every generator — for every language, every protocol, every test — reads from this same model. Code and companion Markdown are generated in the same pass, so **they never drift out of sync**.

### Q: How do I drive a tool?

| Entry point | How |
|-------------|-----|
| **GUI** | Launch the executable with **no arguments**; drive the five tabs (Welcome → Source Code → Source ↔ JSON → JSON ↔ Model → Final Source) |
| **CLI** | Launch with **arguments**; source and target languages are detected from file extensions |
| **MCP API** | Register with the `agent_main_app` beacon; drive through MCP tool calls |
| **Programmatic** | Call `GenerateXxxCode(Model)` from your own Pascal unit; the generators are ordinary Pascal units |

### Q: What MCP tools does each tool expose?

| Tool | MCP tools | Notes |
|------|-----------|-------|
| `code_decl_to_abi` | 31 | Per-language Convert + Read, plus pipeline-level tools |
| `code_decl_to_json_abi` | 3 | `Generate` / `ListFiles` / `GetFile` — deliberate minimal surface |
| `code_decl_to_mcp` | 11 | `SetSourceCode` / `ConvertToXxxMCP` / `GetLastXxxCode` / `Readme` etc. |

**Three-step MCP workflow** (for `code_decl_to_mcp`): `SetSourceCode` → `ConvertToXxxMCP` → `GetLastXxxCode` / `Readme`. No GUI interaction, no CLI invocation, indistinguishable from calling any other MCP tool.

### Q: What types are supported?

Only three normalized type families. **Anything outside these three families causes the entire declaration to be silently dropped.**

- **Integer** — `integer`, `int64`, `cardinal`, `longint`, `dword`, `word`, `smallint`, `byte`, `uint64`, `longword`
- **Float** — `double`, `single`, `extended`, `real`
- **String** — `string`, `ansistring`, `unicodestring`, `tpascalstring`, `tupascalstring`, `tp_string`, `pchar`, `pansichar`, `pwidechar`

**Everything else causes the entire declaration to be silently dropped.** This includes `Boolean`, `Variant`, arrays, records, classes, interfaces, enums, sets, generics, pointers, function pointers, `Currency`, `Comp`, and `TDateTime`.

**Workaround**: serialize complex values into a JSON `string` and deserialize on the receiving side. This is the **only supported escape hatch** for complex types.

**Procedures (no return value)** are valid — they generate `void` return types in target languages. Only the parameter and return **types** are restricted, not the function/procedure distinction.

### Q: What are the known pitfalls?

The knowledge bases document all known pitfalls with stable IDs. See `LingoFuse_Pascal_Complete_Guide.md` (under `src/common/`) for the Pascal core-layer pitfalls:

| ID prefix | Subsystem |
|-----------|-----------|
| `LF-APP-*` | Application/handle layer |
| `LF-CB-*` | Callback layer |
| `LF-DATA-*` | Data handle layer |
| `LF-NET-*` | Network preparation |
| `LF-CALL-*` | Remote call |
| `LF-SEQ-*` | Sequenced notify |
| `LF-CHK-*` | Query/cache |
| `LF-OPT-*` | Runtime options |
| `LF-CLEAN-*` | Cleanup/lifecycle |
| `LF-THREAD-*` | Threading model |
| `LF-TYPE-*` | Types/compilation |
| `LF-XLANG-*` | Cross-language data |
| `LF-JSON-*` | JSON usage layer |

**The four iron rules** (from `LingoFuse_Pascal_Complete_Guide.md`):

1. Callbacks **must** be `cdecl`, and **must not** call blocking LingoFuse functions inside the callback.
2. Data handles **must** be explicitly freed with `LF_FreeData`; do not rely on the 5-minute auto-reclaim.
3. Cleanup order **must** be `LF_ExitMainThread` → `LF_FreeApp` → `LF_Shutdown`.
4. `TZ_JsonObject` is a tree. `Parae` / `Assign` / `LoadFromStream` / `ParseText` may only be called on the **root** object. Use `TZ_JsonString` for intermediate JSON assembly; call `.Bytes` only at the end.

### Q: What is the generated README for?

Every generated artifact is paired with a Markdown companion. **The README is the real deliverable.**

- It contains the **test program**, the **interface reference**, the **build instructions**, and — for C++ — the **CMake script**.
- Code and README are generated from the same `TPascal_Func_Model` in the same pass, so **they never drift out of sync**.
- **Read the generated `.md` first** whenever you are about to build, test, or deploy an artifact.

### Q: How do I add a new target language?

Adding a new target language is a **mechanical 8-step process** (see `code_decl_to_abi_OPERATIONS.md` Chapter 14):

1. Create `<lang>_abi_service_generator_tool.pas`.
2. Create `<lang>_abi_call_generator_tool.pas`.
3. Provide a type mapping table (integer / float / string → target language native types).
4. Register in `code_decl_to_abi.lpr` `uses`.
5. Register in `code_decl_to_abi_cmdline.pas` `uses`, `Detect_Target_Lang`, `Execute_Conversion`.
6. Register in `code_decl_to_abi_frm.pas` `uses`, `GenerateSourceButtonClick`.
7. Add GUI tab sheets and their `TSynEdit` controls to the `.lfm`.
8. Add Convert tools and Readers to the MCP provider; update the `regCount` assertion.

**The backend has no architectural ceiling.** Any language with (a) a C-ABI-compatible FFI, (b) a runtime that speaks LingoFuse's wire protocol, and (c) a way to marshal the three ABI families is a candidate.

### Q: How do I add a new MCP tool?

1. Declare `internal_call_*` in the `interface` section.
2. Implement it in `implementation` using the `TCompute.Sync` pattern.
3. Add an `LF_RegisterCallEx` in `RegisterAPIs`.
4. Add the `ToolDef` assembly + `RegisterTool(ToolDef)` call in `RegisterTools`.
5. Update the `regCount` assertion.

### Q: What is the wire protocol?

**ABI wire format** (from `code_decl_to_abi_OPERATIONS.md` Chapter 7.5):

```
Request  = [field1][field2]...[fieldN]
Response = [status:uint8_t][payload]
  status = 0x00 → payload = serialized result
  status = 0xFF → payload = UTF-8 error message
```

**HTTP/JSON wire format** (from `code_decl_to_json_abi_knowledge_base.md` Chapter 9):

```
Request  = {"args": [v1, v2, ...]}
Response = {"code": 0, "result": <value>}
           {"code": -1, "error": "<message>"}
           {"code": -2, "error": "<message>"}  # request shape error
           {"code": -3, "error": "<message>"}  # precheck failed
```

**MCP tool response format** (from `MCP_API_Contract.md` Chapter 6):

```
Function success : {"result": <value>}
Procedure success: {"status": "ok"}
Any error        : {"error": "<msg>"}
```

### Q: What are the CLI exit codes?

| Code | Meaning |
|:----:|---------|
| 0 | Conversion succeeded |
| 1 | Missing or invalid arguments |
| 2 | Source parsing failed |
| 3 | Code generation failed |
| 4 | File I/O error |

### Q: How do I start an end-to-end service/caller pair?

1. **Start the service** — run the compiled service executable.
2. **Start the bridge** (`code_decl_to_json_abi` only) — `python3 bridge.py --endpoint ipc:<Unit>_abi --port 8081 --no-precheck`.
3. **Start the caller** — run the compiled caller executable or open the HTML test page.

**The bridge must always be running** for any HTTP/JSON call artifact to work. The service itself does not go through the bridge.

### Q: What is the "no drift" guarantee?

All three tools generate **code, tests, build scripts, and companion Markdown from the same `TPascal_Func_Model` in the same pass**. There is no separate "interface definition" that can drift from "interface implementation". This is structurally different from gRPC's `.proto`-to-stub model: `.proto` is a **separate artifact**; `TPascal_Func_Model` is **derived directly from the implementation source**.

---

## 5. File Path Index

### Root

```
LICENSE
readme.md
llms.txt
.gitmodules
```

### `src/common/`

```
lf_http_bridge_client.pas        # HTTP bridge client for Pascal
lingofuse_helper.pas             # RAII high-level wrapper
lingofuse_import.pas             # C ABI import unit
LingoFuse_Pascal_Complete_Guide.md  # Pascal core layer pitfalls KB
```

### `src/pascal_c_to_abi/`

```
code_decl_to_abi.lpr             # Main program (GUI + CLI dispatch)
code_decl_to_abi_cmdline.pas     # CLI frontend
code_decl_to_abi_frm.pas / .lfm  # GUI frontend
code_decl_to_abi_mcp_api_tool_provider_unit.pas  # 31 MCP tools
<lang>_abi_service_generator_tool.pas   # <lang> = pas / py / cpp / csharp / rust / go / java / nodejs / ts / erlang / julia / zig / swift / ruby / fortran / dart / r
<lang>_abi_call_generator_tool.pas      # same <lang> set
<lang>_abi_test_generator_tool.pas      # per-language test program (where applicable)
cpp_abi_cmake_generator_tool.pas        # CMake + C++ test program
pascal_code_abi_rule.md          # Pascal declaration rule
C_code_abi_rule.md               # C declaration rule
code_decl_to_abi_OPERATIONS.md   # Developer knowledge base
code_decl_to_abi_USER_GUIDE.md   # End-to-end user guide
```

**Generator naming pattern**: every target language contributes `<lang>_abi_service_generator_tool.pas` and `<lang>_abi_call_generator_tool.pas`. The 17 `<lang>` values are: `pas`, `py`, `cpp`, `csharp`, `rust`, `go`, `java`, `nodejs`, `ts`, `erlang`, `julia`, `zig`, `swift`, `ruby`, `fortran`, `dart`, `r`.

### `src/pascal_c_to_json_abi/`

```
code_decl_to_json_abi.lpr        # Main program
code_decl_to_json_abi_cmdline.pas # CLI frontend
code_decl_to_abi_json_frm.pas / .lfm  # GUI frontend
code_decl_to_json_abi_mcp_api_tool_provider_unit.pas  # 3 MCP tools
http_<lang>_abi_service_generator_tool.pas   # same 17 <lang> as ABI line
http_<lang>_abi_call_generator_tool.pas      # same 17 <lang>
http_js_abi_call_generator_tool.pas          # JavaScript (browser) — Call only
http_cmake_generator_tool.pas                # CMake + C++ test driver
C_code_abi_rule.md               # C declaration rule
pascal_code_abi_rule.md          # Pascal declaration rule
code_decl_to_json_abi_knowledge_base.md  # Developer knowledge base
code_decl_to_json_abi_USER_GUIDE.md      # End-to-end user guide
```

**Note**: the JSON line additionally has `http_js_abi_call_generator_tool.pas` (Call-only) and `http_bridge_setup_generator_tool.pas` (bridge launch scripts). The 20 target languages are the 17 ABI languages + JavaScript (browser) + PHP + Delphi — but PHP and Delphi also appear in the ABI directory as `<lang>_abi_*` generators for Call-only generation.

### `src/pascal_c_to_mcp/`

```
code_decl_to_mcp.lpr             # Main program
code_decl_to_mcp_cmdline.pas     # CLI frontend
code_decl_to_mcp_frm.pas / .lfm  # GUI frontend
code_decl_to_mcp_api_tool_provider_unit.pas  # 11 MCP tools
pas_mcp_generator_tool.pas       # Pascal MCP generator
py_mcp_generator_tool.pas        # Python MCP generator
cpp_mcp_generator_tool.pas       # C++ MCP generator
csharp_mcp_generator_tool.pas    # C# MCP generator (delivered, not integrated)
cmake_for_cpp_mcp_generator_tool.pas  # CMake + C++ test generator
pascal_code_mcp_rule.md          # Pascal declaration rule for MCP
C_code_mcp_rule.md               # C declaration rule for MCP
MCP_API_Contract.md              # MCP wire-protocol contract
pascal_agent_api_ref_json.md     # Tool registration JSON reference
code_decl_to_mcp_knowledge_base.md  # Developer knowledge base
code_generate_mcp.md             # User manual (V8.0, AI-friendly)
```

### `src/zCore/`

Submodule providing `Z.Core`, `Z.Json`, `Z.Pascal_Func_Model`, `Z.Pascal_Func_Tool`, etc.

---

## 6. Glossary

| Term | Meaning |
|------|---------|
| **LV0** | Raw parser output — syntactic metadata (source positions, raw type spellings, modifiers) |
| **LV1** | Normalized model (`TPascal_Func_Model`) — the only intermediate that generators see |
| **`TPascal_Func_Model`** | The single source of truth for all code and documentation generation |
| **Beacon** | LingoFuse tool registry — agents discover available tools here (default `agent_main_app`) |
| **App name** | LingoFuse application identity; matches case-insensitively on the network |
| **Data handle** (`TDataHnd`) | Opaque byte buffer containing an API name and payload |
| **Sequenced Notify** | FIFO-ordered notification for a given `(App, API)` pair |
| **MCP** | Model Context Protocol — the agent-to-tool communication standard |
| **Bridge** | `bridge.py` — the HTTP↔RPC forwarder required by all HTTP/JSON call artifacts |
| **Companion Markdown** | The `.md` file generated alongside every code artifact; contains build/test/deploy instructions |
| **Companion Markdown is the real deliverable** | The generated `.md` contains the test program, interface reference, build instructions, and CMake script. Read it before building or deploying. |

---

## 7. Repository Metadata

- **Owner**: [PassByYou888](https://github.com/PassByYou888)
- **License**: MIT (consistent with the LingoFuse ecosystem)
- **Language**: English throughout (documents and generated artifacts)
- **Build system**: Lazarus / FPC (`lazbuild`) or Delphi
- **Cross-platform**: Windows, Linux, macOS (any platform with a UI subsystem)
- **Target languages (deduplicated)**: **20**
  - `code_decl_to_abi`: 17 (Service + Call)
  - `code_decl_to_json_abi`: 20 (Service + Call, except JS/PHP/Delphi Call-only)
  - `code_decl_to_mcp`: 4 (Pascal, Python, C++, C#)
- **Roadmap**: 30 target programming languages (mechanical 8-step extension process; no architectural ceiling)

---

## 8. Ecosystem Links

Only repositories that are part of the LingoFuse ecosystem:

| Repository | Description |
|------------|-------------|
| [LingoFuse](https://github.com/PassByYou888/LingoFuse) | Core cross-language RPC framework / distributed system foundation |
| [LingoFuse-Tools](https://github.com/PassByYou888/LingoFuse-Tools) | **This repository.** Code generator suite |
| [LingoFuse-pasAgent-v3](https://github.com/PassByYou888/LingoFuse-pasAgent-v3) | Pascal agent runtime (multimodal) |
| [LingoFuse-pasAgent](https://github.com/PassByYou888/LingoFuse-pasAgent) | Previous-generation Pascal agent |
| [LingoFuse-cppAgent](https://github.com/PassByYou888/LingoFuse-cppAgent) | C++ integration layer |
| [zIPC](https://github.com/PassByYou888/zIPC) | Same-machine IPC engine under LingoFuse |

---

## 9. What This Repository Is Not

- **Not a general-purpose code-generation framework.** It generates cross-language bindings for LingoFuse. It does not generate ORMs, REST clients, protobuf stubs, or anything unrelated to LingoFuse's wire protocol.
- **Not an IDL-first system.** There is no separate IDL. The declaration **is** the implementation. This is why there is no IDL-drift failure mode.
- **Not a "one command, all languages, no setup" tool.** The generators themselves must be built (FPC / Lazarus). Target-language build scripts require the target language's toolchain to be installed. The generator guarantees **the generated code is complete**; it does not guarantee **your machine has every compiler pre-installed**.
- **Not suitable for object-in / object-out interfaces.** Types outside the three ABI families are dropped. You must make a serialization decision at the declaration level. This is deliberate friction, not a defect.
- **Not a community-supported project.** Single maintainer. Issues are answered, but no SLA, no Stack Overflow, no third-party tutorials.

---

*This file follows the [llms.txt](https://llmstxt.org/) convention. It is intended to be consumed by LLM agents and crawlers.*
*Last updated: 2026-11-08*

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free