İçeriğe geç
ajan.io

Belgeler menüsü

Bu sayfada

MCP araçlarında dosya girişi

ajan'da MCP araçlarına dosya iletmeyi öğrenin. Bir MCP aracı dosya girdi alanı bildirdiğinde ajan dosya referanslarını yapılandırılmış FileData nesnelerine otomatik çözümler.

Bir MCP aracı format: "file" ile bir girdi alanı bildirdiğinde ajan, LLM'in dosya referansını otomatik yakalar ve MCP sunucusu çağrıyı almadan önce yapılandırılmış bir FileData nesnesine çözümler.

Nasıl çalışır

Kullanıcı sohbette bir dosya eklediğinde ve LLM buna atıfta bulunduğunda (report.pdf gibi bir dosya adı, attachment// gibi bir depolama yolu veya /mnt/data/), ajan motoru o referansı yakalar ve MCP aracınıza iletmeden önce tam bir FileData nesnesine çözümler.

FileData şekli

MCP aracınız şu nesneyi alır:

typescript
{
  fileName: string;       // original filename, e.g. "report.pdf"
  mimeType: string;       // e.g. "image/jpeg", "application/pdf"
  base64: string;         // full file content, base64-encoded
  size: number;           // byte length
  lastModified: Date;
}

.meta({ format: "file" }) işareti

ajan için temel sinyal, Zod şema alanınıza .meta({ format: "file" }) eklemektir. MCP entegrasyonunu kaydettiğinizde ajan JSON şemasında format: "file" algılar ve alanı FILE türü olarak saklar. Yürütme zamanında ajan dosya referansını tam bir FileData nesnesine çözümler ve MCP sunucunuza iletir.

MCP sunucunuzda dosya girişi uygulama

Girdi alanını FileData şekline uyan bir Zod nesnesi olarak bildirin. z.string() kullanmayın — MCP SDK işleyiciyi çağırmadan önce girdileri doğrular; bu nedenle şema gerçekte alınanla eşleşmelidir:

typescript
server.registerTool(
  "process-file",
  {
    inputSchema: {
      file: z
        .object({
          fileName: z.string(),
          mimeType: z.string(),
          base64: z.string(),
          size: z.number().optional(),
        })
        .describe("File to process")
        .meta({ format: "file" }), // tells ajan to resolve the reference
    },
  },
  async ({ file }) => {
    const buffer = Buffer.from(file.base64, "base64");
    // use buffer, file.fileName, file.mimeType, etc.
    return {
      content: [{ type: "text", text: `Processed: ${file.fileName} (${file.size} bytes)` }],
    };
  },
);

Örnek araç girdisi ve çıktısı

ajan aracınızı çağırdığında tam çözümlenmiş bir FileData nesnesi gönderir:

json
{
  "file": {
    "fileName": "example.txt",
    "mimeType": "text/plain",
    "base64": "SGVsbG8gd29ybGQ=",
    "size": 11
  }
}

Aracınız ardından meta veri veya işlenmiş sonuçlar döndürebilir:

json
{
  "success": true,
  "filename": "example.txt",
  "mimeType": "text/plain",
  "sizeBytes": 11
}

Örnek proje

ajan_mcp_file_upload deposu, şema bildiriminden çözümlenmiş FileData'yı araç işleyicisinde işlemeye kadar tam dosya girişi akışını gösteren minimal çalışan bir MCP sunucusudur.

İlgili belgeler

SSS

Harici MCP aracının ajan'da kullanıcının atıfta bulunduğu bir dosyayı incelemesi veya işlemesi gerektiğinde dosya girişi kullanın. Bu, dosyaları ayrıştıran, dönüştüren, doğrulayan veya başka bir sisteme yükleyen araçlar için kullanışlıdır.

MCP aracının bir dosya girdi alanı bildirdiğini, kullanıcının kullanılabilir bir dosyaya atıfta bulunduğunu, dosya türünün araç tarafından desteklendiğini ve aracın ajan'ın gönderdiği dosya veri biçimini işlediğini kontrol edin.