link-mcp 1.0.0__tar.gz

link_mcp-1.0.0/.gitignore

@@ -0,0 +1,48 @@
+# Personal data — never commit
+raw/*
+!raw/.gitkeep
+
+wiki/sources/*
+!wiki/sources/.gitkeep
+
+wiki/concepts/*
+!wiki/concepts/.gitkeep
+
+wiki/entities/*
+!wiki/entities/.gitkeep
+
+wiki/comparisons/*
+!wiki/comparisons/.gitkeep
+
+wiki/explorations/*
+!wiki/explorations/.gitkeep
+
+# Keep index and log templates but ignore personal content
+# (we ship empty versions in the repo)
+
+# OS junk
+.DS_Store
+*.swp
+*~
+
+# Python
+__pycache__/
+*.pyc
+
+# Autoresearch session files
+autoresearch.jsonl
+autoresearch.md
+autoresearch.sh
+autoresearch.checks.sh
+autoresearch.ideas.md
+autoresearch/
+
+# Integration artifacts (generated by install scripts)
+CLAUDE.md
+AGENTS.md
+GEMINI.md
+GEMINI.md
+.cursor/
+.kiro/
+.github/copilot-instructions.md
+.vscode/settings.json

link_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: link-mcp
+Version: 1.0.0
+Summary: MCP server for the Link personal knowledge wiki — search, context, and graph traversal
+Project-URL: Homepage, https://github.com/gowtham0992/link
+Project-URL: Repository, https://github.com/gowtham0992/link
+License: MIT
+Keywords: ai,knowledge-base,llm,mcp,wiki
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# link-mcp
+
+MCP server for the [Link](https://github.com/gowtham0992/link) personal knowledge wiki.
+
+Exposes your wiki as MCP tools so any MCP-compatible agent can search, query context, and traverse the knowledge graph without reading files directly.
+
+## Install
+
+```bash
+pip install link-mcp
+```
+
+## Setup
+
+1. Install Link and scaffold your wiki:
+```bash
+git clone https://github.com/gowtham0992/link.git
+bash link/integrations/kiro/install.sh
+```
+
+2. Add to your MCP client config:
+```json
+{
+  "mcpServers": {
+    "link": {
+      "command": "python3",
+      "args": ["-m", "link_mcp"]
+    }
+  }
+}
+```
+
+Or with a custom wiki path:
+```json
+{
+  "mcpServers": {
+    "link": {
+      "command": "python3",
+      "args": ["-m", "link_mcp", "--wiki", "/path/to/wiki"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_wiki` | Ranked search by title, alias, tag, fulltext |
+| `get_context` | Topic + full graph neighborhood in one call |
+| `get_pages` | List all pages with metadata |
+| `get_backlinks` | Inbound + forward links for a page |
+| `get_graph` | All nodes + edges |
+| `rebuild_backlinks` | Rebuild the link index |
+
+## Wiki location
+
+By default uses `~/link/wiki/`. Override with `--wiki /path/to/wiki`.

link_mcp-1.0.0/README.md

@@ -0,0 +1,58 @@
+# link-mcp
+
+MCP server for the [Link](https://github.com/gowtham0992/link) personal knowledge wiki.
+
+Exposes your wiki as MCP tools so any MCP-compatible agent can search, query context, and traverse the knowledge graph without reading files directly.
+
+## Install
+
+```bash
+pip install link-mcp
+```
+
+## Setup
+
+1. Install Link and scaffold your wiki:
+```bash
+git clone https://github.com/gowtham0992/link.git
+bash link/integrations/kiro/install.sh
+```
+
+2. Add to your MCP client config:
+```json
+{
+  "mcpServers": {
+    "link": {
+      "command": "python3",
+      "args": ["-m", "link_mcp"]
+    }
+  }
+}
+```
+
+Or with a custom wiki path:
+```json
+{
+  "mcpServers": {
+    "link": {
+      "command": "python3",
+      "args": ["-m", "link_mcp", "--wiki", "/path/to/wiki"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `search_wiki` | Ranked search by title, alias, tag, fulltext |
+| `get_context` | Topic + full graph neighborhood in one call |
+| `get_pages` | List all pages with metadata |
+| `get_backlinks` | Inbound + forward links for a page |
+| `get_graph` | All nodes + edges |
+| `rebuild_backlinks` | Rebuild the link index |
+
+## Wiki location
+
+By default uses `~/link/wiki/`. Override with `--wiki /path/to/wiki`.

link_mcp-1.0.0/link_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""Link MCP Server — personal knowledge wiki as MCP tools."""
+__version__ = "1.0.0"

link_mcp-1.0.0/link_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point: python -m link_mcp"""
+from link_mcp.server import mcp
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

link_mcp-1.0.0/link_mcp/server.py

@@ -0,0 +1,494 @@
+#!/usr/bin/env python3
+"""
+Link MCP Server
+
+Exposes the Link personal knowledge wiki as MCP tools.
+Agents can search, query context, and traverse the knowledge graph
+without reading files directly.
+
+Install:
+  pip install link-mcp
+
+Usage:
+  python -m link_mcp                      # uses ~/link/wiki/
+  python -m link_mcp --wiki /path/wiki    # custom wiki path
+
+Add to your MCP client config:
+  {
+    "mcpServers": {
+      "link": {
+        "command": "python3",
+        "args": ["-m", "link_mcp"]
+      }
+    }
+  }
+"""
+from __future__ import annotations
+import argparse, json, re, sys
+from pathlib import Path
+
+# ── Resolve wiki directory ────────────────────────────────────────────
+parser = argparse.ArgumentParser(add_help=False)
+parser.add_argument("--wiki", default=None)
+args, _ = parser.parse_known_args()
+
+if args.wiki:
+    WIKI_DIR = Path(args.wiki).expanduser().resolve()
+else:
+    WIKI_DIR = Path.home() / "link" / "wiki"
+
+if not WIKI_DIR.exists():
+    print(f"[link-mcp] Wiki not found at {WIKI_DIR}. Run install.sh first.", file=sys.stderr)
+    sys.exit(1)
+
+# ── Import MCP SDK ────────────────────────────────────────────────────
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError:
+    print("[link-mcp] mcp package not found. Install with: pip install mcp", file=sys.stderr)
+    sys.exit(1)
+
+mcp = FastMCP(
+    "link",
+    instructions=(
+        "Link is a personal knowledge wiki. Use search_wiki to find pages, "
+        "get_context to retrieve a topic with its full graph neighborhood, "
+        "and get_pages to browse all pages. Always prefer get_context over "
+        "reading files directly — it returns the primary page plus related "
+        "pages via graph traversal in one call."
+    ),
+)
+
+# ── In-memory indexes (built on first use, invalidated by mtime) ──────
+_cache: dict = {}
+_cache_mtime: float = 0.0
+
+
+def _wiki_mtime() -> float:
+    try:
+        t = WIKI_DIR.stat().st_mtime
+        for child in WIKI_DIR.iterdir():
+            if child.is_dir():
+                t = max(t, child.stat().st_mtime)
+        for name in ("index.md", "log.md", "_backlinks.json"):
+            p = WIKI_DIR / name
+            if p.exists():
+                t = max(t, p.stat().st_mtime)
+        return t
+    except Exception:
+        return 0.0
+
+
+def _parse_frontmatter(text: str) -> tuple[dict, str]:
+    if not text.startswith("---"):
+        return {}, text
+    end = text.find("---", 3)
+    if end == -1:
+        return {}, text
+    meta: dict = {}
+    for line in text[3:end].strip().splitlines():
+        if ":" in line:
+            k, v = line.split(":", 1)
+            v = v.strip().strip('"').strip("'")
+            if v.startswith("[") and v.endswith("]"):
+                v = [x.strip().strip('"').strip("'") for x in v[1:-1].split(",")]
+            meta[k.strip()] = v
+    return meta, text[end + 3:].strip()
+
+
+def _build_cache() -> dict:
+    global _cache, _cache_mtime
+    mtime = _wiki_mtime()
+    if _cache and mtime == _cache_mtime:
+        return _cache
+
+    pages = []
+    page_index: dict[str, Path] = {}
+    fulltext: dict[str, str] = {}
+    snippet_index: dict[str, str] = {}
+    token_index: dict[str, set] = {}
+    meta_token_index: dict[str, set] = {}
+
+    for md in sorted(WIKI_DIR.rglob("*.md")):
+        if md.name.startswith("."):
+            continue
+        rel = md.relative_to(WIKI_DIR)
+        text = md.read_text(encoding="utf-8", errors="replace")
+        meta, body = _parse_frontmatter(text)
+
+        title = meta.get("title", "")
+        if not title:
+            m = re.search(r"^#\s+(.+)", body, re.MULTILINE)
+            title = m.group(1) if m else md.stem
+
+        tldr = ""
+        tldr_m = re.search(r">\s*\*\*TLDR:\*\*\s*(.+)", body)
+        if tldr_m:
+            tldr = tldr_m.group(1).strip()
+
+        aliases_raw = meta.get("aliases", [])
+        if isinstance(aliases_raw, str):
+            aliases_raw = [a.strip() for a in aliases_raw.split(",") if a.strip()]
+        aliases = [a.lower() for a in aliases_raw]
+
+        tags_raw = meta.get("tags", [])
+        if isinstance(tags_raw, str):
+            tags_raw = [t.strip() for t in tags_raw.split(",") if t.strip()]
+
+        cat = rel.parts[0] if len(rel.parts) > 1 else "root"
+        stem = md.stem.lower()
+
+        page = {
+            "name": md.stem,
+            "title": title,
+            "category": cat,
+            "type": meta.get("type", ""),
+            "tags": tags_raw,
+            "aliases": aliases,
+            "maturity": meta.get("maturity", ""),
+            "source_count": meta.get("source_count", ""),
+            "tldr": tldr,
+            "date_updated": meta.get("date_updated", ""),
+            "date_published": meta.get("date_published", ""),
+        }
+        pages.append(page)
+        page_index[stem] = md
+        for alias in aliases:
+            if alias not in page_index:
+                page_index[alias] = md
+
+        text_lower = text.lower()
+        fulltext[stem] = text_lower
+        body_lines = [l.strip() for l in body.split("\n") if l.strip() and not l.startswith("#") and not l.startswith(">")]
+        snippet_index[stem] = body_lines[0][:200] if body_lines else ""
+
+        for token in re.split(r"\W+", text_lower):
+            if len(token) >= 3:
+                token_index.setdefault(token, set()).add(stem)
+
+        meta_tokens: set = set()
+        for word in re.split(r"\W+", title.lower()):
+            if len(word) >= 3:
+                meta_tokens.add(word)
+        for alias in aliases:
+            for word in re.split(r"\W+", alias):
+                if len(word) >= 3:
+                    meta_tokens.add(word)
+        for tag in tags_raw:
+            for word in re.split(r"\W+", str(tag).lower()):
+                if len(word) >= 3:
+                    meta_tokens.add(word)
+        if tldr:
+            for word in re.split(r"\W+", tldr.lower()):
+                if len(word) >= 3:
+                    meta_tokens.add(word)
+        for token in meta_tokens:
+            meta_token_index.setdefault(token, set()).add(stem)
+
+    page_map = {p["name"].lower(): p for p in pages}
+
+    _cache = {
+        "pages": pages,
+        "page_index": page_index,
+        "fulltext": fulltext,
+        "snippet_index": snippet_index,
+        "token_index": token_index,
+        "meta_token_index": meta_token_index,
+        "page_map": page_map,
+    }
+    _cache_mtime = mtime
+    return _cache
+
+
+def _search(q: str, limit: int = 20) -> list[dict]:
+    q_lower = q.lower()
+    c = _build_cache()
+    pages = c["pages"]
+    page_map = c["page_map"]
+    token_index = c["token_index"]
+    meta_token_index = c["meta_token_index"]
+    fulltext = c["fulltext"]
+    snippet_index = c["snippet_index"]
+
+    is_single = bool(re.match(r"^\w+$", q_lower))
+    if is_single and q_lower in token_index:
+        candidates = token_index[q_lower] | meta_token_index.get(q_lower, set())
+    else:
+        candidates = {p["name"].lower() for p in pages}
+
+    scored = []
+    for stem in candidates:
+        p = page_map.get(stem)
+        if not p:
+            continue
+        score = 0
+        if q_lower in p["title"].lower():
+            score += 10
+        if q_lower == stem:
+            score += 20
+        if any(q_lower in a for a in p.get("aliases", [])):
+            score += 8
+        if any(q_lower in str(t).lower() for t in p.get("tags", [])):
+            score += 5
+        if q_lower in p.get("tldr", "").lower():
+            score += 3
+        if fulltext.get(stem, "") and q_lower in fulltext[stem]:
+            score += 2
+        if score > 0:
+            scored.append((score, {**p, "score": score, "snippet": snippet_index.get(stem, "")}))
+
+    scored.sort(key=lambda x: (-x[0], x[1]["title"].lower()))
+    return [r for _, r in scored[:limit]]
+
+
+def _get_context(topic: str) -> dict:
+    c = _build_cache()
+    matches = _search(topic, limit=5)
+    if not matches:
+        return {"topic": topic, "found": False, "pages": []}
+
+    primary = matches[0]
+    primary_name = primary["name"].lower()
+
+    bl_path = WIKI_DIR / "_backlinks.json"
+    backlinks_data: dict = {}
+    if bl_path.exists():
+        try:
+            raw = json.loads(bl_path.read_text(encoding="utf-8"))
+            backlinks_data = raw.get("backlinks", raw)
+        except Exception:
+            pass
+
+    inbound = backlinks_data.get(primary_name, [])
+
+    forward: list[str] = []
+    path = c["page_index"].get(primary_name)
+    if path and path.exists():
+        text = path.read_text(encoding="utf-8", errors="replace")
+        _, body = _parse_frontmatter(text)
+        page_set = {p["name"].lower() for p in c["pages"]}
+        for m in re.finditer(r"\[\[([^\]|]+)(?:\|[^\]]*)?\]\]", body):
+            target = m.group(1).strip().lower()
+            if target in page_set and target != primary_name:
+                forward.append(target)
+
+    seen = {primary_name}
+    context_names = [primary_name]
+    for name in inbound + forward:
+        if name not in seen:
+            seen.add(name)
+            context_names.append(name)
+
+    context_pages = []
+    for name in context_names[:10]:
+        p_path = c["page_index"].get(name)
+        if not p_path or not p_path.exists():
+            continue
+        text = p_path.read_text(encoding="utf-8", errors="replace")
+        meta, body = _parse_frontmatter(text)
+        is_primary = name == primary_name
+        if is_primary:
+            content = body
+        else:
+            lines = body.split("\n")
+            summary = []
+            for line in lines[:20]:
+                summary.append(line)
+                if line.startswith("## ") and len(summary) > 3:
+                    break
+            content = "\n".join(summary)
+
+        page_meta = c["page_map"].get(name, {})
+        context_pages.append({
+            "name": name,
+            "title": meta.get("title", name),
+            "type": meta.get("type", ""),
+            "is_primary": is_primary,
+            "relationship": "primary" if is_primary else ("inbound" if name in inbound else "forward"),
+            "content": content,
+        })
+
+    return {
+        "topic": topic,
+        "found": True,
+        "primary": primary["name"],
+        "inbound_count": len(inbound),
+        "forward_count": len(forward),
+        "pages": context_pages,
+    }
+
+
+# ── MCP Tools ─────────────────────────────────────────────────────────
+
+@mcp.tool()
+def search_wiki(query: str, limit: int = 20) -> str:
+    """Search the Link wiki by title, alias, tag, and full-text content.
+
+    Returns ranked results with scores and snippets. Scoring:
+    - Exact name match: 20pts
+    - Title match: 10pts
+    - Alias match: 8pts
+    - Tag match: 5pts
+    - TLDR match: 3pts
+    - Full-text match: 2pts
+
+    Use this to find relevant pages before calling get_context.
+    """
+    results = _search(query, limit=min(limit, 50))
+    if not results:
+        return json.dumps({"query": query, "count": 0, "results": []})
+    # Strip heavy fields for the search response
+    slim = [{k: v for k, v in r.items() if k not in ("aliases",)} for r in results]
+    return json.dumps({"query": query, "count": len(slim), "results": slim}, ensure_ascii=False)
+
+
+@mcp.tool()
+def get_context(topic: str) -> str:
+    """Get full context for a topic from the Link wiki.
+
+    Returns the best matching page (full content) plus all related pages
+    via graph traversal (inbound links + forward links). This is the
+    primary tool for answering questions — one call gives you everything
+    needed to synthesize an answer.
+
+    The response includes:
+    - primary: the best matching page with full markdown content
+    - inbound: pages that link TO this page
+    - forward: pages this page links TO
+    - relationship field on each page: "primary", "inbound", or "forward"
+    """
+    result = _get_context(topic)
+    return json.dumps(result, ensure_ascii=False)
+
+
+@mcp.tool()
+def get_pages(category: str = "", page_type: str = "", maturity: str = "") -> str:
+    """List all pages in the Link wiki with metadata.
+
+    Optional filters:
+    - category: "concepts", "entities", "sources", "comparisons", "explorations"
+    - page_type: "concept", "entity", "source", "comparison", "exploration"
+    - maturity: "seed", "growing", "mature", "established"
+
+    Returns pages with: name, title, category, type, tags, aliases, maturity,
+    source_count, tldr, date_updated. Does not include full page content.
+    """
+    c = _build_cache()
+    pages = c["pages"]
+    if category:
+        pages = [p for p in pages if p["category"] == category]
+    if page_type:
+        pages = [p for p in pages if p["type"] == page_type]
+    if maturity:
+        pages = [p for p in pages if p["maturity"] == maturity]
+    return json.dumps({"count": len(pages), "pages": pages}, ensure_ascii=False)
+
+
+@mcp.tool()
+def get_backlinks(page_name: str) -> str:
+    """Get all pages that link to or from a given wiki page.
+
+    Returns:
+    - inbound: pages that link TO this page (who references it)
+    - forward: pages this page links TO (what it references)
+
+    Useful for understanding a page's position in the knowledge graph.
+    """
+    bl_path = WIKI_DIR / "_backlinks.json"
+    if not bl_path.exists():
+        return json.dumps({"error": "backlinks not built — run rebuild_backlinks first"})
+    try:
+        raw = json.loads(bl_path.read_text(encoding="utf-8"))
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+    name = page_name.lower().replace(" ", "-")
+    backlinks = raw.get("backlinks", raw)
+    forward = raw.get("forward", {})
+    return json.dumps({
+        "page": page_name,
+        "inbound": backlinks.get(name, []),
+        "forward": forward.get(name, []),
+    }, ensure_ascii=False)
+
+
+@mcp.tool()
+def get_graph() -> str:
+    """Get the full knowledge graph as nodes and edges.
+
+    Returns:
+    - nodes: all wiki pages with id, title, category, type
+    - edges: all [[wikilinks]] as {source, target} pairs
+
+    Useful for understanding the overall structure of the wiki,
+    finding highly-connected pages, or detecting isolated clusters.
+    """
+    c = _build_cache()
+    pages = c["pages"]
+    page_set = {p["name"].lower() for p in pages}
+    nodes = [{"id": p["name"], "title": p["title"], "category": p["category"], "type": p["type"]} for p in pages]
+
+    edges = []
+    wl_re = re.compile(r"\[\[([^\]|]+)(?:\|[^\]]*)?\]\]")
+    for p in pages:
+        source = p["name"]
+        path = c["page_index"].get(source.lower())
+        if not path or not path.exists():
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        _, body = _parse_frontmatter(text)
+        for m in wl_re.finditer(body):
+            target = m.group(1).strip()
+            if target.lower() in page_set and target.lower() != source.lower():
+                edges.append({"source": source, "target": target})
+
+    return json.dumps({"nodes": nodes, "edges": edges}, ensure_ascii=False)
+
+
+@mcp.tool()
+def rebuild_backlinks() -> str:
+    """Rebuild the wiki's backlink index by scanning all [[wikilinks]].
+
+    Call this after ingesting new sources or running lint to ensure
+    the graph index is up to date. Updates wiki/_backlinks.json with
+    both reverse links (backlinks) and forward links.
+    """
+    backlinks: dict[str, list] = {}
+    forward_links: dict[str, list] = {}
+    wl_re = re.compile(r"\[\[([^\]|]+)(?:\|[^\]]*)?\]\]")
+
+    for md in WIKI_DIR.rglob("*.md"):
+        if md.name.startswith("."):
+            continue
+        text = md.read_text(encoding="utf-8", errors="replace")
+        _, body = _parse_frontmatter(text)
+        source = md.stem.lower()
+        for m in wl_re.finditer(body):
+            target = m.group(1).strip().lower()
+            if target != source:
+                backlinks.setdefault(target, [])
+                if source not in backlinks[target]:
+                    backlinks[target].append(source)
+                forward_links.setdefault(source, [])
+                if target not in forward_links[source]:
+                    forward_links[source].append(target)
+
+    result = {"backlinks": backlinks, "forward": forward_links}
+    bl_path = WIKI_DIR / "_backlinks.json"
+    bl_path.write_text(json.dumps(result, indent=2), encoding="utf-8")
+
+    # Invalidate cache
+    global _cache, _cache_mtime
+    _cache = {}
+    _cache_mtime = 0.0
+
+    return json.dumps({"rebuilt": True, "pages_indexed": len(backlinks)})
+
+
+# ── Entry point ───────────────────────────────────────────────────────
+
+def main():
+    mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    main()

link_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "link-mcp"
+version = "1.0.0"
+description = "MCP server for the Link personal knowledge wiki — search, context, and graph traversal"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.0.0"]
+keywords = ["mcp", "knowledge-base", "wiki", "llm", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/gowtham0992/link"
+Repository = "https://github.com/gowtham0992/link"
+
+[project.scripts]
+link-mcp = "link_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["link_mcp"]

link_mcp-1.0.0/server.json

@@ -0,0 +1,19 @@
+{
+  "name": "io.github.gowtham0992/link",
+  "description": "Personal knowledge wiki as MCP tools. Search, query context, and traverse the knowledge graph of your Link wiki. Tools: search_wiki, get_context, get_pages, get_backlinks, get_graph, rebuild_backlinks.",
+  "repository": {
+    "url": "https://github.com/gowtham0992/link",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "link-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}