1use std::path::{Component, Path, PathBuf};
53use std::process::ExitCode;
54use std::sync::atomic::{AtomicBool, Ordering};
55use std::sync::Arc;
56use std::time::Duration;
57
58use docling::{ConvertOptions, DocumentConverter, ImageMode, InputFormat, SourceDocument};
59use rmcp::handler::server::router::tool::ToolRouter;
60use rmcp::handler::server::wrapper::Parameters;
61use rmcp::model::{Implementation, ProgressNotificationParam, ServerCapabilities, ServerConfig};
62use rmcp::service::RequestContext;
63use rmcp::{tool, tool_handler, tool_router, RoleServer, ServerHandler, ServiceExt};
64use serde::Deserialize;
65
66#[derive(Clone, Copy, Debug)]
71pub struct Launcher<'a> {
72 pub command: &'a str,
74 pub client_config: &'a str,
76 pub models_hint: &'a str,
78 pub extra_flags: &'a str,
80}
81
82impl Launcher<'static> {
83 pub const CLI: Self = Self {
85 command: "docling-rs mcp",
86 client_config: "{\"mcpServers\": {\"docling\": {\"command\": \"docling-rs\",\n \"args\": [\"mcp\", \"--root\", \"/Users/me/Documents\"]}}}",
87 models_hint: "Fetch them with scripts/install/download_dependencies.sh (--cli \
88 beside a cargo-installed binary), or point DOCLING_RS_MODELS_DIR at a \
89 .models directory.",
90 extra_flags: "",
91 };
92}
93
94fn help(launcher: &Launcher) -> String {
95 let cmd = launcher.command;
96 let pad = " ".repeat(cmd.len());
97 format!(
98 "\
99{cmd} — a Model Context Protocol server over the docling.rs converter
100
101usage: {cmd} [--root DIR]... [--allow-url-fetch] [--concurrency N]
102 {cmd} --http [--host HOST] [--port PORT] [--allow-remote]
103 {pad} [--bearer-token TOKEN] [...]
104
105Tools: convert_to_markdown(uri) (MarkItDown's MCP tool, same contract),
106convert(uri, to, images, options), list_input_formats().
107
108 --root DIR directory local paths and file: URIs may read from;
109 repeatable (default: the working directory)
110 --allow-url-fetch convert http(s) URLs, remote <img src> and a
111 request-supplied vlm_endpoint (outbound requests from
112 this machine; private and loopback targets stay refused
113 unless DOCLING_RS_ALLOW_PRIVATE_IP_FETCH=1)
114 --concurrency N conversions running at once (default 2)
115 --http serve Streamable HTTP at /mcp instead of stdio
116 --host HOST bind address for --http (default 127.0.0.1)
117 --port PORT port for --http (default 3001)
118 --allow-remote let --http bind a non-loopback address
119 --bearer-token T require `Authorization: Bearer T` on --http
120 (default: DOCLING_RS_MCP_TOKEN when set)
121{}
122Claude Desktop (claude_desktop_config.json):
123 {}",
124 if launcher.extra_flags.is_empty() {
125 String::new()
126 } else {
127 format!("{}\n", launcher.extra_flags.trim_end())
128 },
129 launcher.client_config
130 )
131}
132
133struct Root {
138 given: PathBuf,
139 canonical: PathBuf,
140}
141
142impl Root {
143 fn new(dir: &str) -> Result<Self, String> {
144 let canonical = std::fs::canonicalize(dir).map_err(|e| format!("--root {dir}: {e}"))?;
145 if !canonical.is_dir() {
146 return Err(format!("--root {dir}: not a directory"));
147 }
148 let given = std::path::absolute(dir).map_err(|e| format!("--root {dir}: {e}"))?;
149 Ok(Self {
150 given: normalize(&given),
151 canonical,
152 })
153 }
154}
155
156struct State {
158 roots: Vec<Root>,
161 allow_url_fetch: bool,
162 fetch_policy: docling::FetchPolicy,
164 permits: Arc<tokio::sync::Semaphore>,
165 warned_text_layer: AtomicBool,
167 command: String,
169 models_hint: String,
171 warm: docling::WarmPipeline,
175}
176
177struct HttpConfig {
178 host: String,
179 port: u16,
180 allow_remote: bool,
181 token: Option<String>,
182}
183
184pub fn run(args: Vec<String>) -> ExitCode {
187 ExitCode::from(run_with(args, &Launcher::CLI))
188}
189
190pub fn run_with(args: Vec<String>, launcher: &Launcher) -> u8 {
195 if std::env::var_os("DOCLING_RS_NO_ARENA").is_none() {
201 std::env::set_var("DOCLING_RS_NO_ARENA", "1");
202 }
203 let usage = |err: &str| usage(launcher, err);
204 let mut roots: Vec<String> = Vec::new();
205 let mut allow_url_fetch = false;
206 let mut concurrency: usize = 2;
207 let mut http = false;
208 let mut host = "127.0.0.1".to_string();
209 let mut port: u16 = 3001;
210 let mut allow_remote = false;
211 let mut token = docling_core::env::nonempty("DOCLING_RS_MCP_TOKEN");
212 let mut http_flag: Option<&'static str> = None;
215 let args = match split_flag_values(args) {
216 Ok(args) => args,
217 Err(e) => return usage(&e),
218 };
219 let mut it = args.into_iter();
220 while let Some(arg) = it.next() {
221 match arg.as_str() {
222 "--help" | "-h" => {
223 println!("{}", help(launcher));
224 return 0;
225 }
226 "--root" => match it.next() {
227 Some(v) if !v.is_empty() => roots.push(v),
228 _ => return usage("--root needs a directory"),
229 },
230 "--allow-url-fetch" => allow_url_fetch = true,
231 "--concurrency" => match it.next().and_then(|v| v.parse().ok()) {
232 Some(n) if n >= 1 => concurrency = n,
233 _ => return usage("--concurrency needs a positive integer"),
234 },
235 "--http" => http = true,
236 "--host" => match it.next() {
237 Some(v) if !v.is_empty() => {
238 host = v;
239 http_flag = Some("--host");
240 }
241 _ => return usage("--host needs an address"),
242 },
243 "--port" => match it.next().and_then(|v| v.parse().ok()) {
244 Some(p) => {
245 port = p;
246 http_flag = Some("--port");
247 }
248 None => return usage("--port needs a port number"),
249 },
250 "--allow-remote" => {
251 allow_remote = true;
252 http_flag = Some("--allow-remote");
253 }
254 "--bearer-token" => match it.next() {
255 Some(v) if !v.is_empty() => {
256 token = Some(v);
257 http_flag = Some("--bearer-token");
258 }
259 _ => return usage("--bearer-token needs a token"),
260 },
261 other => return usage(&format!("unknown argument '{other}'")),
262 }
263 }
264 if let (false, Some(flag)) = (http, http_flag) {
265 return usage(&format!("{flag} applies to --http only"));
266 }
267 let defaulted = roots.is_empty();
268 if defaulted {
269 roots.push(".".to_string());
270 }
271 let roots = match roots
272 .iter()
273 .map(|r| Root::new(r))
274 .collect::<Result<Vec<_>, _>>()
275 {
276 Ok(roots) => roots,
277 Err(e) => return usage(&e),
278 };
279 if defaulted && roots[0].canonical.parent().is_none() {
283 return usage(&format!(
284 "the working directory is the file system root ({}); pass --root DIR \
285 to choose what the server may read",
286 roots[0].canonical.display()
287 ));
288 }
289 let state = Arc::new(State {
290 roots,
291 allow_url_fetch,
292 fetch_policy: fetch_policy(),
293 permits: Arc::new(tokio::sync::Semaphore::new(concurrency)),
294 warned_text_layer: AtomicBool::new(false),
295 command: launcher.command.to_string(),
296 models_hint: launcher.models_hint.to_string(),
297 warm: docling::WarmPipeline::new(),
298 });
299 docling::memory::pin_mmap_threshold();
302 let runtime = match tokio::runtime::Runtime::new() {
303 Ok(rt) => rt,
304 Err(e) => {
305 eprintln!("error: tokio runtime: {e}");
306 return 1;
307 }
308 };
309 let result = if http {
310 let cfg = HttpConfig {
311 host,
312 port,
313 allow_remote,
314 token,
315 };
316 runtime.block_on(serve_http(state, cfg))
317 } else {
318 runtime.block_on(serve_stdio(state))
319 };
320 runtime.shutdown_background();
323 match result {
324 Ok(()) => 0,
325 Err(e) => {
326 eprintln!("error: {e}");
327 1
328 }
329 }
330}
331
332fn split_flag_values(args: Vec<String>) -> Result<Vec<String>, String> {
337 const SWITCHES: [&str; 3] = ["--allow-url-fetch", "--http", "--allow-remote"];
338 let mut out = Vec::with_capacity(args.len());
339 for arg in args {
340 let Some((flag, value)) = arg.split_once('=').filter(|(f, _)| f.starts_with("--")) else {
341 out.push(arg);
342 continue;
343 };
344 if SWITCHES.contains(&flag) {
345 match value.to_ascii_lowercase().as_str() {
346 "" | "true" | "1" | "yes" | "on" => out.push(flag.to_string()),
347 "false" | "0" | "no" | "off" => {}
348 _ => return Err(format!("{flag} takes true or false, not '{value}'")),
349 }
350 } else {
351 out.push(flag.to_string());
352 out.push(value.to_string());
353 }
354 }
355 Ok(out)
356}
357
358fn usage(launcher: &Launcher, err: &str) -> u8 {
359 eprintln!("error: {err}");
360 eprintln!(
361 "usage: {} [--root DIR]... [--allow-url-fetch] [--concurrency N] [--http [--host HOST] [--port PORT] [--allow-remote] [--bearer-token TOKEN]]",
362 launcher.command
363 );
364 2
365}
366
367fn describe(state: &State, transport: &str) {
370 eprintln!(
371 "{} {} · {transport} · root {} · URL fetch {}",
372 state.command,
373 env!("CARGO_PKG_VERSION"),
374 state.roots_display(),
375 if state.allow_url_fetch { "on" } else { "off" }
376 );
377}
378
379impl State {
380 fn roots_display(&self) -> String {
382 let roots: Vec<String> = self
383 .roots
384 .iter()
385 .map(|r| r.given.display().to_string())
386 .collect();
387 roots.join(", ")
388 }
389}
390
391async fn serve_stdio(state: Arc<State>) -> Result<(), String> {
392 describe(&state, "stdio");
393 let service = DoclingMcp::new(state)
394 .serve(rmcp::transport::stdio())
395 .await
396 .map_err(|e| format!("mcp: {e}"))?;
397 service
398 .waiting()
399 .await
400 .map(|_| ())
401 .map_err(|e| format!("mcp: {e}"))
402}
403
404async fn serve_http(state: Arc<State>, cfg: HttpConfig) -> Result<(), String> {
405 use rmcp::transport::streamable_http_server::session::local::LocalSessionManager;
406 use rmcp::transport::streamable_http_server::{
407 StreamableHttpServerConfig, StreamableHttpService,
408 };
409
410 let addr = tokio::net::lookup_host((cfg.host.as_str(), cfg.port))
411 .await
412 .map_err(|e| format!("--host {}: {e}", cfg.host))?
413 .next()
414 .ok_or_else(|| format!("--host {}: no address", cfg.host))?;
415 let loopback = addr.ip().is_loopback();
416 if !loopback && !cfg.allow_remote {
417 return Err(format!(
418 "refusing to bind {addr}: not a loopback address — the server reads files under \
419 its root for whoever can reach it; pass --allow-remote (and --bearer-token) to \
420 expose it"
421 ));
422 }
423 if !loopback && cfg.token.is_none() {
424 eprintln!(
425 "warning: serving {addr} without a bearer token — anyone who can reach it can \
426 read the files under the root"
427 );
428 }
429 let mut config = StreamableHttpServerConfig::default();
430 let ct = config.cancellation_token.clone();
432 config = if loopback {
433 config.with_allowed_origins(["http://localhost:*", "http://127.0.0.1:*", "http://[::1]:*"])
438 } else {
439 config.disable_allowed_hosts()
442 };
443 let service: StreamableHttpService<DoclingMcp, LocalSessionManager> =
444 StreamableHttpService::new(
445 {
446 let state = state.clone();
447 move || Ok(DoclingMcp::new(state.clone()))
448 },
449 Default::default(),
450 config,
451 );
452 let mut router = axum::Router::new().nest_service("/mcp", service);
453 if let Some(token) = cfg.token.clone() {
454 let expected: Arc<[u8]> = format!("Bearer {token}").into_bytes().into();
455 router = router.layer(axum::middleware::from_fn(
456 move |req: axum::extract::Request, next: axum::middleware::Next| {
457 let expected = expected.clone();
458 async move {
459 let given = req
460 .headers()
461 .get(axum::http::header::AUTHORIZATION)
462 .map(|v| v.as_bytes())
463 .unwrap_or_default();
464 if constant_time_eq(given, &expected) {
465 next.run(req).await
466 } else {
467 axum::response::IntoResponse::into_response((
468 axum::http::StatusCode::UNAUTHORIZED,
469 [(axum::http::header::WWW_AUTHENTICATE, "Bearer")],
470 "missing or wrong bearer token\n",
471 ))
472 }
473 }
474 },
475 ));
476 }
477 let listener = tokio::net::TcpListener::bind(addr)
478 .await
479 .map_err(|e| format!("binding {addr}: {e}"))?;
480 let bound = listener.local_addr().map_err(|e| e.to_string())?;
481 describe(&state, &format!("Streamable HTTP on http://{bound}/mcp"));
482 axum::serve(listener, router)
483 .with_graceful_shutdown(async move {
484 shutdown_signal().await;
485 ct.cancel();
486 })
487 .await
488 .map_err(|e| format!("serving {bound}: {e}"))
489}
490
491async fn shutdown_signal() {
494 #[cfg(unix)]
495 let terminate = async {
496 match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
497 Ok(mut s) => {
498 s.recv().await;
499 }
500 Err(_) => std::future::pending::<()>().await,
501 }
502 };
503 #[cfg(not(unix))]
504 let terminate = std::future::pending::<()>();
505 tokio::select! {
506 _ = tokio::signal::ctrl_c() => {}
507 _ = terminate => {}
508 }
509}
510
511fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
514 if a.len() != b.len() {
515 return false;
516 }
517 a.iter().zip(b).fold(0u8, |acc, (x, y)| acc | (x ^ y)) == 0
518}
519
520#[derive(Deserialize, schemars::JsonSchema)]
523struct ConvertToMarkdownArgs {
524 uri: String,
529}
530
531#[derive(Deserialize, schemars::JsonSchema)]
532struct ConvertArgs {
533 uri: String,
538 #[serde(default)]
547 #[schemars(transform = drop_null)]
548 to: Option<String>,
549 #[serde(default)]
552 #[schemars(transform = drop_null)]
553 images: Option<String>,
554 #[serde(default)]
562 #[schemars(transform = drop_null)]
563 options: Option<serde_json::Map<String, serde_json::Value>>,
564}
565
566fn drop_null(schema: &mut schemars::Schema) {
569 if let Some(serde_json::Value::Array(types)) = schema.get("type").cloned() {
570 let kept: Vec<_> = types.into_iter().filter(|t| t != "null").collect();
571 if let [single] = kept.as_slice() {
572 schema.insert("type".into(), single.clone());
573 }
574 }
575 if schema.get("default") == Some(&serde_json::Value::Null) {
576 schema.remove("default");
577 }
578}
579
580#[derive(Clone)]
583struct DoclingMcp {
584 state: Arc<State>,
585 tool_router: ToolRouter<Self>,
586}
587
588impl DoclingMcp {
589 fn new(state: Arc<State>) -> Self {
590 Self {
591 state,
592 tool_router: Self::tool_router(),
593 }
594 }
595
596 async fn run_conversion(
599 &self,
600 request: Request,
601 ctx: &RequestContext<RoleServer>,
602 ) -> Result<String, String> {
603 let permit = self
604 .state
605 .permits
606 .clone()
607 .acquire_owned()
608 .await
609 .map_err(|e| e.to_string())?;
610 let state = self.state.clone();
611 let mut job = tokio::task::spawn_blocking(move || {
615 let _permit = permit;
616 let result = convert(&state, &request);
617 docling::memory::release_free_memory();
620 result
621 });
622 let token = ctx.meta.get_progress_token();
623 let mut tick = tokio::time::interval(Duration::from_secs(10));
624 tick.tick().await; let mut beats = 0u32;
626 loop {
627 tokio::select! {
628 done = &mut job => {
629 return done.map_err(|e| format!("conversion worker failed: {e}"))?;
630 }
631 _ = tick.tick(), if token.is_some() => {
632 beats += 1;
633 let param = ProgressNotificationParam::new(
634 token.clone().expect("guarded"),
635 f64::from(beats),
636 )
637 .with_message(format!("converting ({}s)", beats * 10));
638 let _ = ctx.peer.notify_progress(param).await;
639 }
640 }
641 }
642 }
643}
644
645#[tool_router]
646impl DoclingMcp {
647 #[tool(annotations(
658 title = "Convert to Markdown",
659 read_only_hint = true,
660 open_world_hint = true
661 ))]
662 async fn convert_to_markdown(
663 &self,
664 Parameters(args): Parameters<ConvertToMarkdownArgs>,
665 ctx: RequestContext<RoleServer>,
666 ) -> Result<String, String> {
667 let request = Request {
668 uri: args.uri,
669 to: "md".into(),
670 images: ImageMode::Placeholder,
671 options: ConvertOptions::default(),
672 };
673 self.run_conversion(request, &ctx).await
674 }
675
676 #[tool(annotations(
687 title = "Convert to a chosen format",
688 read_only_hint = true,
689 open_world_hint = true
690 ))]
691 async fn convert(
692 &self,
693 Parameters(args): Parameters<ConvertArgs>,
694 ctx: RequestContext<RoleServer>,
695 ) -> Result<String, String> {
696 let request = Request::from_args(args)?;
697 self.run_conversion(request, &ctx).await
698 }
699
700 #[tool(annotations(title = "List input formats", read_only_hint = true))]
706 async fn list_input_formats(&self) -> String {
707 let mut out = InputFormat::supported_extensions().join("\n");
708 out.push_str(if self.state.allow_url_fetch {
709 "\n\nURL inputs (http/https): enabled"
710 } else {
711 "\n\nURL inputs (http/https): disabled (the server was started without --allow-url-fetch)"
712 });
713 out
714 }
715}
716
717#[tool_handler(router = self.tool_router)]
718impl ServerHandler for DoclingMcp {
719 fn get_info(&self) -> ServerConfig {
720 let mut info = Implementation::new("docling-rs", env!("CARGO_PKG_VERSION"));
721 info.title = Some("docling.rs".into());
722 info.website_url = Some("https://github.com/docling-project/docling.rs".into());
723 ServerConfig::new(ServerCapabilities::builder().enable_tools().build())
724 .with_server_info(info)
725 .with_instructions(format!(
726 "Converts documents to Markdown or docling JSON for reading: PDF (layout, \
727 tables, OCR), DOCX, PPTX, XLSX, HTML, EPUB, e-mail, images, audio and more. \
728 Tools: convert_to_markdown for Markdown with default settings; convert for \
729 any other output format or for options (e.g. {{\"pages\": \"1-5\"}}); \
730 list_input_formats to check what this server accepts. Local files: paths under {}. URLs: {}.",
731 self.state.roots_display(),
732 if self.state.allow_url_fetch {
733 "enabled"
734 } else {
735 "disabled on this server"
736 }
737 ))
738 }
739}
740
741struct Request {
745 uri: String,
746 to: String,
747 images: ImageMode,
748 options: ConvertOptions,
749}
750
751const OUTPUTS: &[&str] = &[
755 "md", "json", "html", "text", "latex", "chunks", "vtt", "pandoc",
756];
757
758impl Request {
759 fn from_args(args: ConvertArgs) -> Result<Self, String> {
760 let to = match args.to.as_deref().map(str::trim) {
761 None | Some("") | Some("md") | Some("markdown") => "md".to_string(),
762 Some(t) if OUTPUTS.contains(&t) => t.to_string(),
763 Some(t) => {
764 return Err(format!(
765 "unknown to={t:?} (expected one of: {})",
766 OUTPUTS.join(", ")
767 ))
768 }
769 };
770 let images = match args.images.as_deref().map(str::trim) {
771 None | Some("") | Some("placeholder") => ImageMode::Placeholder,
772 Some("embedded") => ImageMode::Embedded,
773 Some(other) => {
774 return Err(format!(
775 "unknown images={other:?} (expected: placeholder, embedded)"
776 ))
777 }
778 };
779 let options = match args.options {
780 None => ConvertOptions::default(),
781 Some(map) => {
782 let unknown = ConvertOptions::unknown_keys(map.keys().map(String::as_str), &[]);
783 if let Some(key) = unknown.first() {
784 return Err(format!(
785 "options: unknown field `{key}` (see docs/OPTIONS.md for the list)"
786 ));
787 }
788 ConvertOptions::from_loose_json(map).map_err(|e| format!("options: {e}"))?
791 }
792 };
793 Ok(Self {
794 uri: args.uri,
795 to,
796 images,
797 options,
798 })
799 }
800}
801
802fn convert(state: &State, request: &Request) -> Result<String, String> {
805 let source = resolve_source(state, &request.uri)?;
806 let mut options = guard_options(state, &request.options)?;
807 if request.to == "md" && options.compact_tables.is_none() {
811 options.compact_tables = Some(true);
812 }
813 let document = convert_document(state, &source, &options)?;
814 render(
815 &document,
816 &request.to,
817 request.images,
818 request.options.track_changes().ok().flatten(),
819 )
820}
821
822fn warn_partial(state: &State, source: &SourceDocument, errors: &[docling::ErrorItem]) {
827 for e in errors {
828 eprintln!(
829 "{}: {}: partial document: {}",
830 state.command,
831 source.name,
832 e.describe()
833 );
834 }
835}
836
837fn convert_document(
838 state: &State,
839 source: &SourceDocument,
840 options: &ConvertOptions,
841) -> Result<docling::DoclingDocument, String> {
842 let converter = options
843 .apply(DocumentConverter::new().warm_pipeline(&state.warm))
844 .map_err(|e| e.to_string())?;
845 if let Some(vlm) = options.vlm_options().map_err(|e| e.to_string())? {
847 let result = docling::vlm::convert_vlm_result(source, &vlm).map_err(|e| e.to_string())?;
848 warn_partial(state, source, &result.errors);
849 let mut document = result.document;
850 converter.finish_document(&mut document);
851 return Ok(document);
852 }
853 match converter.convert(source.clone()) {
854 Ok(result) => {
855 warn_partial(state, source, &result.errors);
856 Ok(result.document)
857 }
858 Err(e)
863 if source.format == InputFormat::Pdf
864 && options.text_layer_only.is_none()
865 && e.to_string().contains("model not found") =>
866 {
867 if !state.warned_text_layer.swap(true, Ordering::Relaxed) {
868 eprintln!(
869 "{}: the layout models are missing, so PDFs convert from their text \
870 layer (no layout analysis, table structure or OCR). {}",
871 state.command, state.models_hint
872 );
873 }
874 let retry = DocumentConverter::new().text_layer_only(true);
877 let converter = options.apply(retry).map_err(|e| e.to_string())?;
878 converter
879 .convert(source.clone())
880 .map(|r| r.document)
881 .map_err(|e| e.to_string())
882 }
883 Err(e) => Err(e.to_string()),
884 }
885}
886
887fn render(
888 document: &docling::DoclingDocument,
889 to: &str,
890 images: ImageMode,
891 track_changes: Option<docling::TrackChanges>,
892) -> Result<String, String> {
893 Ok(match to {
894 "md" => match images {
895 ImageMode::Placeholder => document.export_to_markdown(),
896 mode => document.export_to_markdown_with_images(mode, "artifacts").0,
897 },
898 "json" => document.export_to_json(),
899 "html" => document.export_to_html(),
900 "text" => document.export_to_text(),
901 "latex" => document.export_to_latex(),
902 "vtt" => document.export_to_vtt(),
903 "chunks" => {
904 let mut warn = |msg: String| eprintln!("warning: {msg}");
905 let records = docling::chunks::chunk_records(document, &mut warn);
906 serde_json::to_string_pretty(&records).map_err(|e| e.to_string())?
907 }
908 "pandoc" => {
909 document
910 .export_to_pandoc_json_with(&docling::pandoc::PandocExportOptions {
911 image_mode: images,
912 track_changes,
913 ..Default::default()
914 })
915 .map_err(|e| e.to_string())?
916 .0
917 }
918 other => return Err(format!("unknown to={other:?}")),
919 })
920}
921
922fn guard_options(state: &State, options: &ConvertOptions) -> Result<ConvertOptions, String> {
926 let mut o = options.clone();
927 o.validate().map_err(|e| e.to_string())?;
928 let requested = o.image_sources().map_err(|e| e.to_string())?.or_else(|| {
932 o.fetch_images
933 .filter(|&f| f)
934 .map(|_| docling::ImageSources::Remote)
935 });
936 if requested == Some(docling::ImageSources::Remote) && !state.allow_url_fetch {
937 o.image_sources = Some(docling::ImageSources::Embedded.to_string());
938 o.fetch_images = Some(false);
939 }
940 if let Some(endpoint) = o.vlm_endpoint.as_deref().filter(|v| !v.trim().is_empty()) {
941 if !state.allow_url_fetch {
942 return Err(
943 "a request-supplied vlm_endpoint needs the server started with \
944 --allow-url-fetch (or pin it with DOCLING_RS_VLM_ENDPOINT)"
945 .into(),
946 );
947 }
948 docling::fetch::check_outbound_url(endpoint, false)?;
949 }
950 if o.use_web_browser == Some(true) && !state.allow_url_fetch {
951 return Err(
952 "use_web_browser loads the page's remote resources; it needs the server \
953 started with --allow-url-fetch"
954 .into(),
955 );
956 }
957 if let Some(dir) = o.xbrl_taxonomy.as_deref() {
958 o.xbrl_taxonomy = Some(local_path(state, Path::new(dir))?.display().to_string());
959 }
960 if let Some(layout) = o.ebcdic_layout.as_deref() {
962 if !layout.trim_start().starts_with('{') {
963 o.ebcdic_layout = Some(local_path(state, Path::new(layout))?.display().to_string());
964 }
965 }
966 if let Some(model) = o.asr_model.as_deref() {
968 if model.contains(['/', '\\']) || model.contains("..") {
969 return Err(format!("asr_model must be a preset name, got {model:?}"));
970 }
971 }
972 Ok(o)
973}
974
975fn resolve_source(state: &State, uri: &str) -> Result<SourceDocument, String> {
978 let uri = uri.trim();
979 if uri.is_empty() {
980 return Err("uri is empty".into());
981 }
982 let lower = uri.get(..8).unwrap_or(uri).to_ascii_lowercase();
983 if lower.starts_with("data:") {
984 return docling::fetch::from_data_url(uri).map_err(|e| e.to_string());
985 }
986 if lower.starts_with("http://") || lower.starts_with("https://") {
987 if !state.allow_url_fetch {
988 return Err(format!(
989 "fetching URLs is disabled on this server (it was started without \
990 --allow-url-fetch); pass a local path or file: URI under {} instead",
991 state.roots_display()
992 ));
993 }
994 return SourceDocument::from_url(uri, &state.fetch_policy).map_err(|e| e.to_string());
995 }
996 let path = if lower.starts_with("file:") {
997 docling::fetch::file_url_path(uri)?
998 } else if let Some(scheme) = uri_scheme(uri) {
999 return Err(format!(
1000 "unsupported URI scheme {scheme:?} (expected http, https, file, data, or a path)"
1001 ));
1002 } else {
1003 PathBuf::from(uri)
1004 };
1005 let path = local_path(state, &path)?;
1006 if path.is_dir() {
1007 return Err(format!("{} is a directory, not a document", path.display()));
1008 }
1009 match SourceDocument::from_file(&path) {
1010 Ok(source) => Ok(source),
1011 Err(_) => {
1013 let bytes = std::fs::read(&path).map_err(|e| format!("{}: {e}", path.display()))?;
1014 let name = path
1015 .file_name()
1016 .and_then(|n| n.to_str())
1017 .unwrap_or("document");
1018 let mut source = SourceDocument::from_named_bytes(name, bytes, None)
1019 .map_err(|e| format!("{}: {e}", path.display()))?;
1020 source.path = Some(path);
1021 Ok(source)
1022 }
1023 }
1024}
1025
1026fn fetch_policy() -> docling::FetchPolicy {
1033 docling::FetchPolicy {
1034 max_redirects: 5,
1035 ..docling::FetchPolicy::default()
1036 }
1037}
1038
1039fn uri_scheme(uri: &str) -> Option<&str> {
1042 let (scheme, _) = uri.split_once(':')?;
1043 let valid = scheme.len() >= 2
1044 && scheme.starts_with(|c: char| c.is_ascii_alphabetic())
1045 && scheme
1046 .chars()
1047 .all(|c| c.is_ascii_alphanumeric() || matches!(c, '+' | '-' | '.'));
1048 valid.then_some(scheme)
1049}
1050
1051fn local_path(state: &State, path: &Path) -> Result<PathBuf, String> {
1059 let joined = if path.is_absolute() {
1060 path.to_path_buf()
1061 } else {
1062 state.roots[0].canonical.join(path)
1063 };
1064 let outside = || {
1065 format!(
1066 "{} is outside the server's root ({}); start the server with --root to allow it",
1067 path.display(),
1068 state.roots_display()
1069 )
1070 };
1071 let lexical = normalize(&joined);
1072 let under = |p: &Path| {
1073 let p = plain(p);
1074 state
1075 .roots
1076 .iter()
1077 .any(|r| p.starts_with(plain(&r.given)) || p.starts_with(plain(&r.canonical)))
1078 };
1079 if !under(&lexical) {
1080 return Err(outside());
1081 }
1082 let canonical = std::fs::canonicalize(&lexical)
1083 .map_err(|e| format!("cannot open {}: {e}", path.display()))?;
1084 if !state
1085 .roots
1086 .iter()
1087 .any(|r| canonical.starts_with(&r.canonical))
1088 {
1089 return Err(outside());
1090 }
1091 Ok(canonical)
1092}
1093
1094fn plain(path: &Path) -> PathBuf {
1100 #[cfg(windows)]
1101 {
1102 let text = path.to_string_lossy();
1103 if let Some(rest) = text.strip_prefix(r"\\?\") {
1104 return match rest.strip_prefix(r"UNC\") {
1105 Some(unc) => PathBuf::from(format!(r"\\{unc}")),
1106 None => PathBuf::from(rest),
1107 };
1108 }
1109 }
1110 path.to_path_buf()
1111}
1112
1113fn normalize(path: &Path) -> PathBuf {
1115 let mut out = PathBuf::new();
1116 for component in path.components() {
1117 match component {
1118 Component::ParentDir => {
1119 out.pop();
1120 }
1121 Component::CurDir => {}
1122 other => out.push(other),
1123 }
1124 }
1125 out
1126}
1127
1128#[cfg(test)]
1132mod tests {
1133 use super::*;
1134
1135 fn state(root: &Path, allow_url_fetch: bool) -> State {
1136 State {
1137 roots: vec![Root::new(root.to_str().unwrap()).unwrap()],
1138 allow_url_fetch,
1139 fetch_policy: fetch_policy(),
1140 permits: Arc::new(tokio::sync::Semaphore::new(1)),
1141 warned_text_layer: AtomicBool::new(false),
1142 command: Launcher::CLI.command.to_string(),
1143 models_hint: Launcher::CLI.models_hint.to_string(),
1144 warm: docling::WarmPipeline::new(),
1145 }
1146 }
1147
1148 fn fixtures() -> PathBuf {
1149 Path::new(env!("CARGO_MANIFEST_DIR")).join("../../tests/data")
1150 }
1151
1152 #[test]
1153 fn paths_stay_under_the_root() {
1154 let root = fixtures().join("md");
1155 let s = state(&root, false);
1156 let ok = local_path(&s, Path::new("sources")).unwrap();
1158 assert!(ok.ends_with("md/sources"));
1159 for escape in [
1161 "../docx/sources",
1162 "sources/../../docx",
1163 "/etc/passwd",
1164 "/nonexistent/x.pdf",
1165 ] {
1166 let err = local_path(&s, Path::new(escape)).unwrap_err();
1167 assert!(err.contains("outside the server's root"), "{escape}: {err}");
1168 }
1169 }
1170
1171 #[cfg(unix)]
1174 #[test]
1175 fn a_root_behind_a_symlink_takes_both_spellings() {
1176 let dir = std::env::temp_dir().join(format!("docling-mcp-link-{}", std::process::id()));
1177 let _ = std::fs::remove_dir_all(&dir);
1178 std::fs::create_dir_all(&dir).unwrap();
1179 let link = dir.join("docs");
1180 std::os::unix::fs::symlink(fixtures().join("md"), &link).unwrap();
1181 let s = state(&link, false);
1182 let via_link = link.join("sources");
1183 assert!(local_path(&s, &via_link).is_ok());
1184 let via_target = fixtures().join("md/sources");
1185 assert!(local_path(&s, &std::fs::canonicalize(via_target).unwrap()).is_ok());
1186 assert!(local_path(&s, &dir.join("docs/../elsewhere")).is_err());
1187 std::fs::remove_dir_all(&dir).unwrap();
1188 }
1189
1190 #[cfg(windows)]
1193 #[test]
1194 fn a_verbatim_root_takes_a_plain_absolute_path() {
1195 let root = std::fs::canonicalize(fixtures().join("md")).unwrap();
1196 let text = root.to_string_lossy();
1197 let Some(plain_root) = text.strip_prefix(r"\\?\") else {
1198 panic!("not a verbatim path: {text}");
1199 };
1200 let s = state(&root, false);
1201 assert!(local_path(&s, &Path::new(plain_root).join("sources")).is_ok());
1202 assert!(local_path(&s, Path::new(r"C:\Windows\win.ini")).is_err());
1203 }
1204
1205 #[cfg(unix)]
1206 #[test]
1207 fn a_symlink_cannot_lead_out_of_the_root() {
1208 let dir = std::env::temp_dir().join(format!("docling-mcp-{}", std::process::id()));
1209 let _ = std::fs::remove_dir_all(&dir);
1210 std::fs::create_dir_all(&dir).unwrap();
1211 std::os::unix::fs::symlink(fixtures().join("docx"), dir.join("out")).unwrap();
1212 let s = state(&dir, false);
1213 let err = local_path(&s, Path::new("out/sources")).unwrap_err();
1214 assert!(err.contains("outside the server's root"), "{err}");
1215 std::fs::remove_dir_all(&dir).unwrap();
1216 }
1217
1218 #[test]
1219 fn uri_kinds() {
1220 assert_eq!(uri_scheme("s3://bucket/x.pdf"), Some("s3"));
1221 assert_eq!(uri_scheme("ftp://h/x"), Some("ftp"));
1222 assert_eq!(uri_scheme("C:\\docs\\a.pdf"), None);
1223 assert_eq!(uri_scheme("report.pdf"), None);
1224 let s = state(&fixtures(), false);
1225 let err = resolve_source(&s, "ftp://example.com/a.pdf").unwrap_err();
1226 assert!(err.contains("unsupported URI scheme"), "{err}");
1227 let err = resolve_source(&s, "https://example.com/a.pdf").unwrap_err();
1228 assert!(err.contains("--allow-url-fetch"), "{err}");
1229 let err = resolve_source(&s, "docx").unwrap_err();
1230 assert!(err.contains("is a directory"), "{err}");
1231 }
1232
1233 #[test]
1236 fn data_uris_decode() {
1237 let s = state(&fixtures(), false);
1238 let src = resolve_source(&s, "data:text/markdown;base64,IyBUaXRsZQoKSGVsbG8=").unwrap();
1239 assert_eq!(src.format, InputFormat::Md);
1240 assert_eq!(src.bytes, b"# Title\n\nHello");
1241 let src = resolve_source(&s, "DATA:text/html,%3Ch1%3EHi%3C/h1%3E").unwrap();
1242 assert_eq!(src.format, InputFormat::Html);
1243 assert_eq!(src.bytes, b"<h1>Hi</h1>");
1244 let src = resolve_source(&s, "data:;base64,JVBERi0xLjQK").unwrap();
1246 assert_eq!(src.format, InputFormat::Pdf);
1247 let src = resolve_source(&s, "data:text/csv;charset=shift_jis,a,b").unwrap();
1248 assert_eq!(src.encoding.as_deref(), Some("shift_jis"));
1249 assert!(resolve_source(&s, "data:text/plain").is_err());
1250 let src = resolve_source(&s, "data:application/octet-stream,xyz").unwrap();
1252 assert_eq!(src.format, InputFormat::Text);
1253 assert!(resolve_source(&s, "data:application/octet-stream;base64,AAECAwQF").is_err());
1254 }
1255
1256 #[test]
1257 fn options_follow_the_operator_policy() {
1258 let s = state(&fixtures(), false);
1259 let opts: ConvertOptions =
1260 serde_json::from_value(serde_json::json!({"image_sources": "remote"})).unwrap();
1261 let guarded = guard_options(&s, &opts).unwrap();
1262 assert_eq!(guarded.image_sources.as_deref(), Some("embedded"));
1263 let opts: ConvertOptions =
1264 serde_json::from_value(serde_json::json!({"vlm_endpoint": "http://h/v1"})).unwrap();
1265 assert!(guard_options(&s, &opts)
1266 .unwrap_err()
1267 .contains("--allow-url-fetch"));
1268 let opts: ConvertOptions =
1269 serde_json::from_value(serde_json::json!({"xbrl_taxonomy": "/etc"})).unwrap();
1270 assert!(guard_options(&s, &opts).unwrap_err().contains("outside"));
1271 let opts: ConvertOptions =
1272 serde_json::from_value(serde_json::json!({"asr_model": "../../x"})).unwrap();
1273 assert!(guard_options(&s, &opts)
1274 .unwrap_err()
1275 .contains("preset name"));
1276 let s = state(&fixtures(), true);
1278 let opts: ConvertOptions =
1279 serde_json::from_value(serde_json::json!({"fetch_images": true})).unwrap();
1280 let guarded = guard_options(&s, &opts).unwrap();
1281 assert_ne!(guarded.image_sources.as_deref(), Some("embedded"));
1282 }
1283
1284 #[test]
1285 fn requests_validate_their_arguments() {
1286 let args = |v: serde_json::Value| serde_json::from_value::<ConvertArgs>(v).unwrap();
1287 let r = Request::from_args(args(serde_json::json!({"uri": "a.docx"}))).unwrap();
1288 assert_eq!(r.to, "md");
1289 let err = Request::from_args(args(serde_json::json!({"uri": "a", "to": "dclx"})))
1290 .map(|_| ())
1291 .unwrap_err();
1292 assert!(err.contains("unknown to"), "{err}");
1293 let err = Request::from_args(args(
1294 serde_json::json!({"uri": "a", "options": {"text_layer_onyl": true}}),
1295 ))
1296 .map(|_| ())
1297 .unwrap_err();
1298 assert!(err.contains("unknown field `text_layer_onyl`"), "{err}");
1299 let r = Request::from_args(args(
1300 serde_json::json!({"uri": "a", "to": "json", "options": {"pages": "1-2"}}),
1301 ))
1302 .unwrap();
1303 assert_eq!(r.options.pages.as_deref(), Some("1-2"));
1304 let r = Request::from_args(args(serde_json::json!({
1306 "uri": "a",
1307 "options": {"force_full_page_ocr": "true", "ocr_scale": "1.5", "pages": "3", "video_frames": 2}
1308 })))
1309 .unwrap();
1310 assert_eq!(r.options.force_full_page_ocr, Some(true));
1311 assert_eq!(r.options.ocr_scale, Some(1.5));
1312 assert_eq!(r.options.pages.as_deref(), Some("3"));
1313 assert_eq!(r.options.video_frames, Some(2));
1314 let err = Request::from_args(args(
1315 serde_json::json!({"uri": "a", "options": {"force_full_page_ocr": "maybe"}}),
1316 ))
1317 .map(|_| ())
1318 .unwrap_err();
1319 assert!(
1320 err.contains("force_full_page_ocr: cannot read \"maybe\""),
1321 "{err}"
1322 );
1323 }
1324
1325 #[test]
1326 fn converts_a_docx_to_compact_markdown() {
1327 let s = state(&fixtures(), false);
1328 let request = Request {
1329 uri: "docx/sources/lorem_ipsum.docx".into(),
1330 to: "md".into(),
1331 images: ImageMode::Placeholder,
1332 options: ConvertOptions::default(),
1333 };
1334 let md = convert(&s, &request).unwrap();
1335 assert!(md.contains("Lorem ipsum"), "{md}");
1336 }
1337
1338 #[test]
1341 fn calls_on_the_warm_pipeline_keep_their_own_options() {
1342 let warm = state(&fixtures(), false);
1343 let request = |pages: Option<&str>| Request {
1344 uri: "pdf/sources/2206.01062.pdf".into(),
1345 to: "json".into(),
1346 images: ImageMode::Placeholder,
1347 options: ConvertOptions {
1348 text_layer_only: Some(docling::TextLayerOnly::On),
1349 pages: pages.map(str::to_string),
1350 ..Default::default()
1351 },
1352 };
1353 for pages in [Some("2-3"), None, Some("1-1"), None] {
1354 let cold = convert(&state(&fixtures(), false), &request(pages)).unwrap();
1355 assert_eq!(
1356 convert(&warm, &request(pages)).unwrap(),
1357 cold,
1358 "pages {pages:?}"
1359 );
1360 }
1361 }
1362
1363 #[test]
1365 fn flags_accept_the_equals_spelling() {
1366 let v = |a: &[&str]| split_flag_values(a.iter().map(|s| s.to_string()).collect());
1367 assert_eq!(
1368 v(&[
1369 "--root=/a",
1370 "--allow-url-fetch=true",
1371 "--http=false",
1372 "--port=9"
1373 ])
1374 .unwrap(),
1375 ["--root", "/a", "--allow-url-fetch", "--port", "9"]
1376 );
1377 assert_eq!(v(&["--root", "/a=b"]).unwrap(), ["--root", "/a=b"]);
1378 assert!(v(&["--allow-url-fetch=maybe"]).is_err());
1379 }
1380
1381 #[test]
1384 fn tool_schemas_are_portable() {
1385 let schema = serde_json::to_value(schemars::schema_for!(ConvertArgs)).unwrap();
1386 assert_eq!(schema["required"], serde_json::json!(["uri"]));
1387 for (name, ty) in [
1388 ("to", "string"),
1389 ("images", "string"),
1390 ("options", "object"),
1391 ] {
1392 let prop = &schema["properties"][name];
1393 assert_eq!(prop["type"], ty, "{name}: {prop}");
1394 assert!(prop.get("default").is_none(), "{name}: {prop}");
1395 }
1396 let args: ConvertArgs = serde_json::from_value(
1398 serde_json::json!({"uri": "a.md", "to": null, "images": null, "options": null}),
1399 )
1400 .unwrap();
1401 assert_eq!(Request::from_args(args).unwrap().to, "md");
1402 }
1403
1404 #[test]
1405 fn bearer_comparison() {
1406 assert!(constant_time_eq(b"Bearer abc", b"Bearer abc"));
1407 assert!(!constant_time_eq(b"Bearer abd", b"Bearer abc"));
1408 assert!(!constant_time_eq(b"Bearer ab", b"Bearer abc"));
1409 assert!(!constant_time_eq(b"", b"Bearer abc"));
1410 }
1411}